Metasys REST API (5.370)

Download OpenAPI specification:Download

Introduction

The Metasys REST API is the exposed interface for accessing data from a Johnson Controls® Metasys system. This spec documents v5 of the API first released as part of Metasys 13.0. This documentation was last updated on June 25, 2024 at 2:12 PM (UTC).

Note
The Metasys REST API is only supported on the following Metasys products: ADS, ADX, and OAS. The REST API is not supported on Metasys for Validated Environments (MVE) sites. Do not attempt to use the REST API on an MVE site.

This version of the documentation includes INTERNAL operations which are only for use by approved Johnson Controls teams/projects.

This version of the documentation includes PRIVATE operations which are only to be used by Metasys developers for Metasys products. These operations should not be shared with other teams within Johnson Controls, nor should they be shared with third parties outside of Johnson Controls.

Metasys is a network-based building automation system (BAS) that operates the mechanical and electrical equipment in your building. For an introduction to Metasys, refer to Metasys System in Metasys System Configuration Guide. For a glossary of Metasys terms, refer to Metasys System Glossary. For additional information on Metasys, search the Johnson Controls documentation site Knowledge Exchange.

This specification defines the operations you can use to retrieve data through the API. For further information on the Metasys API, including tutorials, see the Metasys API home page.

© 2022 Johnson Controls Tyco IP Holdings LLP.

Base URL

This documentation is for Metasys 13.0 which ships with version 5 of the Metasys Server.

The base path for the API is https://{hostname}/api/v5 where {hostname} is the host name of your Metasys server.

API Version Notes

Multiple versions of this API may be supported on one release of Metasys. At Metasys 13.0, the supported versions are v4 and v5. (However, v4 is deprecated and may be removed in a future release.)

Note: Versions earlier than v4 are not available on Metasys 13.0.

You must specify which version you intend to use in the URL, using the format v[#].

For example, https://localhost/api/v5/spaces for version 5 of spaces.

Documentation for v3 and earlier can be found here.

Version Response Behavior

The Content-Type header of the response will always contain (in part) the version of the API that was used to serve the request. This allows you to identify which version of the API was utilized.

For example, Content-Type: application/vnd.metasysapi.v5+json for version 5.

Licensed Operations

You must obtain an additional license to access some operations. For more information, refer to the Licensing information and Software information sections in Metasys System Software Purchase Options Product Bulletin (LIT-12011703).

Monitoring and Commanding API license

The Monitoring and Commanding API enables reading, writing, and commanding one or more Metasys objects/properties, including Present Value. This API succeeds the Metasys System Secure Data Access dynamic link library (MSSDA DLL).

The following operations require the Monitoring and Commanding API license:

Case Sensitivity Rules

In general, you should assume that all URLs, parameter names, parameter values, payload property names and payload property values are case sensitive. For example:

  • All attributes of objects are case sensitive. For example, many objects have an attribute named presentValue. It is case sensitive and must always be spelled presentValue.
  • Enumeration set names and set members are case sensitive (for example, reliabilityEnumSet.reliable, displayPrecisionEnumSet.displayPrecision1, and writePriorityEnumSet.priorityDefault).

Pagination

For operations where page and pageSize is allowed, the default page number will be 1 and is 1-based for all paths while the default pageSize will vary between paths. The page parameter indicates the page number of items to return from the path. The pageSize parameter indicates the maximum number of items in the response from the path.

Payloads returned by pagination-enabled paths have a similar structure. A total property indicates the total number of items included in all pages. A next and previous property supplies a link to the next and previous page of data, respectively. These properties can be empty if irrelevant (for example, if it is the first/last page, or there is only one page of data). The items property contains the data included in the page.

Sorting Rules

For operations where a sort query parameter is allowed, the supplied value should be in the format of a single attribute name, optionally prefixed with - to indicate descending sort order (ascending order is used if no prefix is supplied).

DateTimes

All date-times in the alarms, audits, activities, and samples operations are ISO-8601 encoded strings in UTC. Other operations, such as objects, use a proprietary structure further described in supporting documentation.

Validation and Common Error Codes

There are some general rules that apply across all operations. If certain provided inputs are invalid or preconditions are not met, the API will respond with an appropriate error to indicate what went wrong.

Condition Error Details
Invalid request body 400 (Bad Request) A body is provided which does not adhere to the expected format and/or schema
Missing required parameter 400 (Bad Request) A parameter marked required in this document is not included in the request
Parameter incorrect type 400 (Bad Request) A parameter is included with a value of the wrong type (for example, number is expected and string is provided)
Parameter out of range 400 (Bad Request) A numeric parameter is included but the value is outside the allowed range
Parameter not in set 400 (Bad Request) A string parameter has a set of predefined valid values, and the value provided is not included in that set
Parameter not in correct format 400 (Bad Request) A string parameter with expected format is provided in the wrong format
Unsupported Content-Type 400 (Bad Request) An unsupported Content-Type header is provided
User not authenticated 401 (Unauthorized) The auth token supplied with the request is missing, invalid, or expired
Record not authorized 403 (Forbidden) The user is not authorized to view data matching the provided identifier or too many requests
Invalid user type 403 (Forbidden) Not an "API user"; not all user accounts have API access
API version not supported for MVE 403 (Forbidden) An operation was attempted against a validated resource using a version of an API not supported for MVE
Identifier not found 404 (Not Found) An identifier is provided that does not match any known data
The resource already exists 409 (Conflict) The resource already exists
Internal Server Error 500 (Internal Server Error) An unexpected error occurred
The device is not supported 501 (Not Implemented) The server does not support the functionality required to fulfill the request
A service is unavailable 503 (Service Unavailable) A service is currently unavailable to service the request.
The device is offline 504 (Bad Gateway) An attempt was made to talk to another device that is currently offline.

Schemas in Response Payloads

The response payload of some operations in this document have a section of information labeled schema. This section of information includes important pieces of metadata about the item or items attributes that gives better context to the meaning of attribute values. This section follows JSON Schema specification with added custom annotation keywords.

Security

Bearer-Authentication

Most of the calls in the API use bearer token authentication. What this means is that these requests require an Authorization header to be set to a value with the following format: Bearer: {accessToken}. Use the /login operation to request an accessToken. An example of the full header would look like the following: Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1....

Note: This example access token is truncated.

The expiration time of the access token is based on the user's Metasys profile.

Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer
Bearer format: JWT

API-Key-Authentication

The Streaming operation is the only operation to use API key authentication, because web browsers do not allow setting custom headers when initiating Server Sent Event connections.

Security Scheme Type: API Key
Query parameter name: access_token

activities

This section describes the operations you can perform on activities. Activities are a superset of all alarms and audits in a Metasys system. Use activities operations to view audits and alarms. Apply filters to further refine the results.

Activities Event Subscriptions

Subscribe for activity-related events to receive updates when activities are created, discarded, acknowledged, or annotated.

Subscribing

To subscribe for activity-related events, complete the following steps:

  1. Open a stream with the Get a stream operation. Take note of the stream ID.
  2. Use Get Activities and include a METASYS-SUBSCRIBE header with the stream ID.

Note: Any filters added to the original GET operation also apply the event subscription.

Unsubscribing

To unsubscribe from an activities event subscription, complete the following steps:

  1. Get the METASYS-SUBSCRIPTION-LOCATION from the subscribe operation response.
  2. Issue a Delete activities subscription request to METASYS-SUBSCRIPTION-LOCATION.

See also:

Events

There are five event types sent by the activities subscription: acknowledged, annotate, discard, new, and heartbeat.

  • activity.heartbeat - A heartbeat event is sent to show that the subscription is still alive. A heartbeat is a JSON string with the current UTC date time in ISO 8601 format and is sent every 30 seconds.

    Heartbeat Payload Example
    {
      "currentTime": "2021-02-16T16:21:10.23Z",
      "subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"]
    }
    
  • activity.alarm.ack - An alarm acknowledge event is sent to indicate that the management status has changed to acknowledged.

    Acknowledged Alarm Payload Example
    {
      "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
      "activity": {
        "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
        "objectName": "OA_T",
        "activityManagementStatus": "acknowledged",
        "creationTime": "2021-02-16T20:30:00Z",
        "spaces": [
          {
            "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
            "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
            "name": "Floor 1",
            "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
          }
        ],
        "equipment": [
          {
            "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
            "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
            "equipmentName": "Engine1",
            "shortName": null,
            "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
          }
        ],
        "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
        "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
        "alarm": {
          "message": "",
          "alarmGeneratorObject": {
            "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
            "referencedObject": {
              "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
            }
          },
          "isAckRequired": true,
          "acknowledgedTime": "2021-02-16T20:31:02Z",
          "type": "alarmValueEnumSet.avHiAlarm",
          "priority": 70,
          "category": "objectCategoryEnumSet.generalCategory",
          "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
          "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
          "triggerValue": {
            "item": "2.0",
            "schema": {
              "type": "string",
              "metasysType": "string",
              "units": {
                "id": "unitEnumSet.degF",
                "title": "deg F"
              }
            }
          },
          "description": ""
        }
      },
      "effectivePermission": {
        "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "canAcknowledge": true,
        "canDiscard": true,
        "canAnnotate": true
      }
    }
    
  • activity.alarm.annotate - An alarm annotate event is sent when an annotation is added to an alarm activity, providing the information for the annotated alarm.

    Annotate Alarm Payload Example
    {
      "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
      "activity": {
        "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
        "objectName": "OA_T",
        "activityManagementStatus": "pending",
        "creationTime": "2021-02-16T20:30:00Z",
        "spaces": [
          {
            "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
            "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
            "name": "Floor 1",
            "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
          }
        ],
        "equipment": [
          {
            "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
            "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
            "equipmentName": "Engine1",
            "shortName": null,
            "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
          }
        ],
        "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
        "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
        "alarm": {
          "message": "",
          "alarmGeneratorObject": {
            "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
            "referencedObject": {
              "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
            }
          },
          "isAckRequired": true,
          "acknowledgedTime": "2021-02-16T20:31:02Z",
          "type": "alarmValueEnumSet.avHiAlarm",
          "priority": 70,
          "category": "objectCategoryEnumSet.generalCategory",
          "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
          "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
          "triggerValue": {
            "item": "2.0",
            "schema": {
              "type": "string",
              "metasysType": "string",
              "units": {
                "id": "unitEnumSet.degF",
                "title": "deg F"
              }
            }
          },
          "description": ""
        }
      },
      "effectivePermission": {
        "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "canAcknowledge": true,
        "canDiscard": true,
        "canAnnotate": true
      }
    }
    
  • activity.alarm.discard - An alarm discard event is sent when the management status of an alarm activity changes to discarded.

    Discard Alarm Payload Example
    {
      "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
      "activity": {
        "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
        "objectName": "OA_T",
        "activityManagementStatus": "discarded",
        "creationTime": "2021-02-16T20:30:00Z",
        "spaces": [
          {
            "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
            "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
            "name": "Floor 1",
            "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
          }
        ],
        "equipment": [
          {
            "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
            "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
            "equipmentName": "Engine1",
            "shortName": null,
            "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
          }
        ],
        "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
        "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
        "alarm": {
          "message": "",
          "alarmGeneratorObject": {
            "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
            "referencedObject": {
              "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
            }
          },
          "isAckRequired": true,
          "acknowledgedTime": "2021-02-16T20:31:02Z",
          "type": "alarmValueEnumSet.avHiAlarm",
          "priority": 70,
          "category": "objectCategoryEnumSet.generalCategory",
          "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
          "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
          "triggerValue": {
            "item": "2.0",
            "schema": {
              "type": "string",
              "metasysType": "string",
              "units": {
                "id": "unitEnumSet.degF",
                "title": "deg F"
              }
            }
          },
          "description": ""
        }
      },
      "effectivePermission": {
        "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "canAcknowledge": true,
        "canDiscard": true,
        "canAnnotate": true
      }
    }
    
  • activity.alarm.new - A new alarm event is sent when an alarm activity is created.

    New Alarm Payload Example
    {
      "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
      "activity": {
        "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
        "objectName": "OA_T",
        "activityManagementStatus": "pending",
        "creationTime": "2021-02-16T20:30:00Z",
        "spaces": [
          {
            "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
            "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
            "name": "Floor 1",
            "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
          }
        ],
        "equipment": [
          {
            "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
            "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
            "equipmentName": "IDU1",
            "shortName": null,
            "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
          }
        ],
        "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
        "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
        "alarm": {
          "message": "",
          "alarmGeneratorObject": {
            "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
            "referencedObject": {
              "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
            }
          },
          "isAckRequired": true,
          "type": "alarmValueEnumSet.avHiAlarm",
          "priority": 70,
          "category": "objectCategoryEnumSet.generalCategory",
          "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
          "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
          "triggerValue": {
            "item": "2.0",
            "schema": {
              "type": "string",
              "metasysType": "string",
              "units": {
                "id": "unitEnumSet.degF",
                "title": "deg F"
              }
            }
          },
          "description": ""
        }
      },
      "effectivePermission": {
        "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
        "canAcknowledge": true,
        "canDiscard": true,
        "canAnnotate": true
      }
    }
    
  • activity.audit.new - A new audit event is sent when an audit activity is created.

    New Audit Payload Example
    {
      "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
      "activity": {
        "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
        "itemReference": "{hostname}:{deviceHostname}",
        "objectName": "MS-NAE5510-3",
        "activityManagementStatus": "pending",
        "creationTime": "2021-02-16T16:21:10.23Z",
        "objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
        "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
        "audit": {
          "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
          "status": null,
          "preData": null,
          "postData": {
            "item": "10.10.198.131",
            "schema": {
              "type": "string",
              "metasysType": "string"
            }
          },
          "parameters": [],
          "errorString": null,
          "user": "MetasysSysAgent",
          "signature": null,
          "classLevel": "auditClassesEnumSet.userActionAuditClass",
          "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
          "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
          "annotationsUrl": null,
          "self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
        }
      },
      "effectivePermission": {
        "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
        "canDiscard": true
      }
    }
    
  • activity.audit.annotate - An annotate audit event is sent when an annotation is added to an audit activity, providing the information for the annotated audit.

    Annotate Audit Payload Example
    {
      "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
      "activity": {
        "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
        "itemReference": "{hostname}:{deviceHostname}",
        "objectName": "MS-NAE5510-3",
        "activityManagementStatus": "pending",
        "creationTime": "2021-02-16T16:21:10.23Z",
        "objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
        "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
        "audit": {
          "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
          "status": null,
          "preData": null,
          "postData": {
            "item": "10.10.198.131",
            "schema": {
              "type": "string",
              "metasysType": "string"
            }
          },
          "parameters": [],
          "errorString": null,
          "user": "MetasysSysAgent",
          "signature": null,
          "classLevel": "auditClassesEnumSet.userActionAuditClass",
          "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
          "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
          "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
          "self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
        }
      },
      "effectivePermission": {
        "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
        "canDiscard": true
      }
    }
    
  • activity.audit.discard - An audit discard event is sent when the management status of an audit activity changes to discarded.

    Discard Audit Payload Example
    {
      "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
      "activity": {
        "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
        "itemReference": "{hostname}:{deviceHostname}",
        "objectName": "MS-NAE5510-3",
        "activityManagementStatus": "discarded",
        "creationTime": "2021-02-16T16:21:10.23Z",
        "objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
        "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
        "audit": {
          "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
          "status": null,
          "preData": null,
          "postData": {
            "item": "10.10.198.131",
            "schema": {
              "type": "string",
              "metasysType": "string"
            }
          },
          "parameters": [],
          "errorString": null,
          "user": "MetasysSysAgent",
          "signature": null,
          "classLevel": "auditClassesEnumSet.userActionAuditClass",
          "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
          "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
          "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
          "self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
        }
      },
      "effectivePermission": {
        "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
        "canDiscard": true
      }
    }
    

Filter Behavior

Filters supplied to an activities request limit the results to activities for which the filters apply. When subscribing to an activities request that uses filters, the events received are also limited to the same filter criteria. Exceptions to this behavior occur when filtering on activity management status, such as for acknowledged or discarded activities. You receive an update whenever an activity management change occurs, regardless of filters, because the change can impact the original set of activities you subscribed to. For example, consider the following scenario:

  • You subscribe to acknowledged activities and receive all acknowledged activities, receiving updates for any acknowledged thereafter across the stream.
  • In this state, one of the activities in your original list is discarded by another user.

When this occurs, you receive an activity.alarm.discard message for the discarded activity even though your filters exclude activities that are discarded. This is necessary so that you can properly maintain the state of activities already received in your application.

Priority Alarm Event Subscriptions

The priority alarm is the newest, highest priority alarm that is pending required acknowledgement by the current user. A user can subscribe to receive the initial and all subsequent changes to the current priority alarm and total pending acknowledgement alarm count over streaming notifications.

Subscribing

To subscribe for priority alarm notifications, complete the following steps:

  1. Open a stream with the Get a stream operation. Take note of the stream ID.
  2. Use the Create priority alarm subscription operation using the stream ID in the URL.

Unsubscribing

To unsubscribe from a priority alarm subscription, complete the following steps:

  1. Get the Location from the subscribe operation response.
  2. Issue a Delete priority alarm subscription request to Location.

See also:

Events

There are two event types sent by the priority alarm subscription:

  • activities.priorityAlarm.heartbeat - A heartbeat event is sent to show that one or more subscriptions are still alive. A heartbeat is a JSON string with the current UTC date time in ISO 8601 format and is sent every 30 seconds.
currentTime
required
string <date-time>

Current server time in ISO8601 format

subscriptionIds
required
Array of strings

List of all active subscriptionIds for this stream

{
  • "currentTime": "2022-01-01T00:00:00Z",
  • "subscriptionIds": [
    ]
}
  • activities.priorityAlarm.update - An update event is sent when the current priority alarm changes and/or the total pending acknowledgement alarm count changes
subscriptionIds
required
Array of strings <uuid> [ items <uuid > ]

Subscription IDs that the notification apply to

total
required
integer <int32>

Total alarms pending acknowledgement

object or null

Current priority alarm. If null and total is 0, then all alarms are acknowledged. If null and total is >0, then all alarms are snoozed

{
  • "subscriptionIds": [
    ],
  • "total": 5,
  • "item": {
    }
}

List activities

Retrieves a collection of activities.

Authorizations:
Bearer-Authentication
query Parameters
activityType
Array of strings[ items <= 2 items ]
Items Enum: "alarm" "audit"
Example: activityType=alarm

Limit the activities returned to a specific type

includeDiscarded
boolean

Determines whether discarded activities will be included in the results or be the only type of activity in the results. Discarded activities are those for which the activityManagementStatus is discarded.

This parameter can produce 3 different types of results.

  • true - Return only discarded activities in the response.
  • false - Do not include any discarded activities in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded activities are returned.
continuationToken
string
Example: continuationToken=eyJhdWRpdCI6eyJpZCI6IjgOTQ2NjUzLTlmM...

Provide a token from a previous request to fetch the next set of results. Ignored for streaming subscriptions.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether activities which can be acknowledged are included in the results. When the value is true, activities which can be acknowledged will be included in the results. When false, activities which can be acknowledged will not be included in the results.

The use of this parameter implies a filter of activityType=alarm and the results will not include any audits.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether activities which can not be acknowledged are included in the results. When the value is true then the results will include activities which cannot be acknowledged. When the value is false then the results will not include activities which cannot be acknowledged.

The use of this parameter implies a filter of activityType=alarm and the results will not include any audits.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

originApplication
Array of strings
Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp
metasysEnum: auditOriginAppEnumSet

Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message.

The acceptable values for the elements of this parameter come from the auditOriginAppEnumSet enumeration. Only the long name of the origin application (for example, auditOriginAppEnumSet.deviceManagerAuditOriginApp instead of deviceManagerAuditOriginApp) is accepted. Find the definition of auditOriginAppEnumSet at the relative URL of /schemas/enums/auditOriginAppEnumSet.

See also:

classLevel
Array of strings
Example: classLevel=auditClassesEnumSet.userActionAuditClass
metasysEnum: auditClassesEnumSet

Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose.

The Enabled Audit Level attribute (attributeEnumSet.auditEnabledClasLev) determines which audit levels the system generates. Therefore, be aware that there will be no audits to return if the Enabled Audit Level attribute is set too low to generate audits at the desired class level in this filter. This attribute is set per device (for audits generated on that device).

The acceptable values for the elements of this parameter come from the auditClassesEnumSet enumeration. Only the long name of the class level (for example, auditClassesEnumSet.userActionAuditClass instead of userActionAuditClass) is accepted. Find the definition of auditClassesEnumSet at the relative URL of /schemas/enums/auditClassesEnumSet.

See also:

actionType
Array of strings
Example: actionType=auditActionTypeEnumSet.writeAuditActionType
metasysEnum: auditActionTypeEnumSet

Filter by list of action types. The action type property indicates the user or system action performed.

The acceptable values for the elements of this parameter come from the auditActionTypeEnumSet enumeration. Only the long name of the action type (for example, auditActionTypeEnumSet.writeAuditActionType instead of writeAuditActionType) is accepted. Find the definition of auditActionTypeEnumSet at the relative URL of /schemas/enums/auditActionTypeEnumSet.

See also:

user
Array of strings <= 100 items
Example: user=metasysuser

Filter by list of users. The user property indicates which user initiated the action being audited.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/activities?activityType=alarm&includeDiscarded=false&continuationToken=eyJhdWRpdCI6eyJpZCI6IjgOTQ2NjUzLTlmM...&sort=creationTime&startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&category=objectCategoryEnumSet.hvacCategory&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Batch operations

Used to invoke multiple activity operations in a single HTTP request. In this version of the API, the only activity-related operations that can be used in a batch are listed below.

See also

Authorizations:
Bearer-Authentication
Request Body schema: application/json
required
method
required
string
Enum: "PATCH" "POST"

The HTTP method to use for each request.

required
Array of objects

A collection of entries that represent the operations to invoke.

Responses

Request samples

Content type
application/json
Example

A request to discard multiple activities (2 audits and 2 alarms). One audit request and one alarm request include annotation text and the other requests do not.

{}

Response samples

Content type
application/vnd.metasysapi.v5+json

This is an example response to a batch request. Two of the operations succeeded and two of them failed.

{
  • "responses": [
    ]
}

Delete activities subscription

Deletes a subscription to the activities resource.

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Responses

Request samples

curl --request DELETE \
  --url https://metasys-server.example.com/api/v5/activities/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Create priority alarm subscription (INTERNAL)

Creates a subscription to receive the current and all subsequent changes to the priority alarm and total pending acknowledgement alarm count. If the provided streamId is not valid or authorized, you will not receive an error nor would you receive any stream notifications.

visibility: internal
Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

Responses

Request samples

curl --request POST \
  --url https://metasys-server.example.com/api/v5/activities/priorityAlarm/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Delete priority alarm subscription (INTERNAL)

Deletes a subscription to the current priority alarm.

visibility: internal
Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Responses

Request samples

curl --request DELETE \
  --url https://metasys-server.example.com/api/v5/activities/priorityAlarm/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

alarms

Alarms alert users to potential problems identified by a Metasys system, for example high zone temperatures. Use alarms operations to get object alarms, network device alarms, single alarms, alarm collections, and alarm annotations. Acknowledge or discard alarms with the edit patch operation. Filter the results with the query parameters time, priority, type, category, acknowledgement, and page. Sort the results by creation time and priority.

Get alarms for an object

Retrieves a collection of alarms for the specified object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeDiscarded
boolean

Determines whether discarded alarms will be included in the results or be the only type of alarm in the results. Discarded alarms are those for which the activityManagementStatus is discarded. This parameter can produce 3 different types of results.

  • true - Return only discarded alarms in the response.
  • false - Do not include any discarded alarms in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether alarms which can be acknowledged are included in the results. When the value is true, alarms which can be acknowledged will be included in the results. When false, alarms which can be acknowledged will not be included in the results.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether alarms which can not be acknowledged are included in the results. When the value is true then the results will include alarms which cannot be acknowledged. When the value is false then the results will not include alarms which cannot be acknowledged.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Get alarms for a network device

Retrieves a collection of alarms for the specified network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeDiscarded
boolean

Determines whether discarded alarms will be included in the results or be the only type of alarm in the results. Discarded alarms are those for which the activityManagementStatus is discarded. This parameter can produce 3 different types of results.

  • true - Return only discarded alarms in the response.
  • false - Do not include any discarded alarms in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether alarms which can be acknowledged are included in the results. When the value is true, alarms which can be acknowledged will be included in the results. When false, alarms which can be acknowledged will not be included in the results.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether alarms which can not be acknowledged are included in the results. When the value is true then the results will include alarms which cannot be acknowledged. When the value is false then the results will not include alarms which cannot be acknowledged.

equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Get alarms Deprecated

Retrieves a collection of alarms.

Note: This operation is deprecated and may be removed in a future release. To retrieve alarms, consider using GET /activities?activityType=alarm instead. See List activities

Authorizations:
Bearer-Authentication
query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeDiscarded
boolean

Determines whether discarded alarms will be included in the results or be the only type of alarm in the results. Discarded alarms are those for which the activityManagementStatus is discarded. This parameter can produce 3 different types of results.

  • true - Return only discarded alarms in the response.
  • false - Do not include any discarded alarms in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether alarms which can be acknowledged are included in the results. When the value is true, alarms which can be acknowledged will be included in the results. When false, alarms which can be acknowledged will not be included in the results.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether alarms which can not be acknowledged are included in the results. When the value is true then the results will include alarms which cannot be acknowledged. When the value is false then the results will not include alarms which cannot be acknowledged.

equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Get an alarm

Retrieves the specified alarm.

Authorizations:
Bearer-Authentication
path Parameters
alarmId
required
string
Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5

The identifier of the alarm.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/alarms/4d0598d4-2836-4efd-84b8-6f39754b1fc5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

An alarm for an analog value object.

{}

Edit an alarm

Allows for acknowledging or discarding an alarm.

Authorizations:
Bearer-Authentication
path Parameters
alarmId
required
string
Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5

The identifier of the alarm.

Request Body schema: application/json
required
activityManagementStatus
required
string
Enum: "acknowledged" "discarded"

The new activity management status of the alarm.

The values of this property are described as follows:

  • acknowledged - The alarm has been recognized and viewed by a user. An alarm may only be acknowledged if activityManagementStatus is currently pending and isAckRequired is true.
  • discarded - The alarm has been acted upon and addressed by a user. Once an alarm is discarded, it cannot be changed to any other state.
annotationText
string or null

The annotation associated with the change of alarm state.

Responses

Request samples

Content type
application/json
Example
{
  • "activityManagementStatus": "acknowledged"
}

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "code": "string",
  • "message": "string",
  • "details": { },
  • "innerError": { },
  • "innerErrors": [
    ]
}

Get alarm annotations

Retrieves the collection of annotations available for the specified alarm.

Authorizations:
Bearer-Authentication
path Parameters
alarmId
required
string
Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5

The identifier of the alarm.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "user" "-user"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/alarms/4d0598d4-2836-4efd-84b8-6f39754b1fc5/annotations?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Add alarm annotation (INTERNAL)

Adds an annotation to an alarm.

visibility: internal
Authorizations:
Bearer-Authentication
path Parameters
alarmId
required
string
Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5

The identifier of the alarm.

Request Body schema: application/json
required
text
required
string [ 1 .. 255 ] characters \S

The text of the annotation to create. This must not be null, empty, nor only whitespace. Additionally, any surrounding whitespace will be trimmed.

Responses

Request samples

Content type
application/json
{
  • "text": "Looks okay."
}

announcements

announcements

🛠 Get announcements (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Gets the current announcements

Authorizations:
Bearer-Authentication

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/announcements \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "type": "announcement",
  • "label": "Announcement",
  • "totalCount": 0,
  • "announcements": [ ]
}

🛠 Create announcement (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Create an announcement

Authorizations:
Bearer-Authentication
Request Body schema: application/json
required
label
required
string
enabled
boolean
description
required
string
startDateTime
required
string <date-time>
endDateTime
string <date-time>
toEmailAddresses
required
Array of strings <email> [ items <email > ]
announcementTypes
required
Array of strings
Items Enum: "loginScreen" "banner" "email"

Responses

Request samples

Content type
application/json
{
  • "label": "Important update",
  • "description": "Please review all alarms",
  • "startDateTime": "2023-07-01T10:00:00-6:00",
  • "announcementTypes": [
    ],
  • "toEmailAddresses": [ ]
}

Response samples

Content type
application/vnd.metasysapi.v5+json
3

🛠 Edit announcement (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

undefined

Authorizations:
Bearer-Authentication
Request Body schema: application/json
required
id
required
integer
label
required
string
enabled
boolean
description
required
string
startDateTime
required
string <date-time>
endDateTime
string <date-time>
toEmailAddresses
required
Array of strings <email> [ items <email > ]
announcementTypes
required
Array of strings
Items Enum: "loginScreen" "banner" "email"

Responses

Request samples

Content type
application/json
{
  • "id": 5,
  • "label": "Important update",
  • "description": "Please review all alarms",
  • "startDateTime": "2023-07-01T10:00:00-6:00",
  • "announcementTypes": [
    ],
  • "toEmailAddresses": [ ]
}

Response samples

Content type
application/vnd.metasysapi.v5+json
3

🛠 Get announcement (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

undefined

Authorizations:
Bearer-Authentication
path Parameters
announcementId
integer
Example: 3

The id of the announcement

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/announcements/3 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "label": "Important update",
  • "description": "Please review all alarms",
  • "startDateTime": "2023-07-01T10:00:00-6:00",
  • "announcementTypes": [
    ],
  • "toEmailAddresses": [ ]
}

🛠 Delete announcement (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

undefined

Authorizations:
Bearer-Authentication
path Parameters
announcementId
required
integer
Example: 3

The id of the announcement

Responses

Request samples

curl --request DELETE \
  --url https://metasys-server.example.com/api/v5/announcements/3 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

🛠 Get latest announcement (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

If no such announcement exists, then you'll get an announcement with default values for all of the properties.

Authorizations:
Bearer-Authentication
path Parameters
announcementType
string
Enum: "loginScreen" "banner" "email"
Example: loginScreen

The announce type

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/announcements/loginScreen/latest \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

This is an example of what this returns if there is no such announcement.

{
  • "id": 0,
  • "type": "announcement",
  • "label": null,
  • "enabled": false,
  • "description": null,
  • "startDateTime": "0001-01-01T00:09:00-05:51",
  • "endDateTime": null,
  • "toEmailAddresses": null,
  • "announcementTypes": null,
  • "isCompleted": true
}

🛠 Dismiss announcement (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Dismisses announcement for current user until announcement is updated again.

Authorizations:
Bearer-Authentication
path Parameters
announcementId
integer
Example: 3

The announcement id

Responses

Request samples

curl --request POST \
  --url https://metasys-server.example.com/api/v5/announcements/3/dismiss \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
5

audits

How to retrieve, discard, and annotate audits.

Relationships

Audits have relationships to other resources in the system. Find information about the most important below.

  • objects

When users or the system affect objects in the Metasys system, such as analog inputs, multistate objects, or binary outputs, audits are generated. Those "acted upon" objects then relate to those audits. That relationship is returned as part of any audit response.

  • equipment instances

Equipment instance associations to audits build off of the objects association explanation. Each equipment instance can contain many points, such as Outdoor Air Temperature, Damper Position, or Zone Setpoint. Those points map to actual objects in Metasys, as noted above. When users or the system affect those objects, audits are generated. If an equipment instance's point is mapped to one of those affected objects the instance is then associated with that audit.

In short, an equipment instance contains points which map to Metasys objects which are affected by an audited action.

  • spaces

Space associations to audits build off of the equipment instance association explanation. Equipment instances can serve spaces, such as an Air Handler Unit (AHU) serving the floor of a building. Therefore, audits associated with a particular equipment instance are associated to the spaces they serve.

Get audits for an object

Retrieves a collection of audits for the specified object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

originApplication
Array of strings
Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp
metasysEnum: auditOriginAppEnumSet

Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message.

The acceptable values for the elements of this parameter come from the auditOriginAppEnumSet enumeration. Only the long name of the origin application (for example, auditOriginAppEnumSet.deviceManagerAuditOriginApp instead of deviceManagerAuditOriginApp) is accepted. Find the definition of auditOriginAppEnumSet at the relative URL of /schemas/enums/auditOriginAppEnumSet.

See also:

classLevel
Array of strings
Example: classLevel=auditClassesEnumSet.userActionAuditClass
metasysEnum: auditClassesEnumSet

Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose.

The Enabled Audit Level attribute (attributeEnumSet.auditEnabledClasLev) determines which audit levels the system generates. Therefore, be aware that there will be no audits to return if the Enabled Audit Level attribute is set too low to generate audits at the desired class level in this filter. This attribute is set per device (for audits generated on that device).

The acceptable values for the elements of this parameter come from the auditClassesEnumSet enumeration. Only the long name of the class level (for example, auditClassesEnumSet.userActionAuditClass instead of userActionAuditClass) is accepted. Find the definition of auditClassesEnumSet at the relative URL of /schemas/enums/auditClassesEnumSet.

See also:

actionType
Array of strings
Example: actionType=auditActionTypeEnumSet.writeAuditActionType
metasysEnum: auditActionTypeEnumSet

Filter by list of action types. The action type property indicates the user or system action performed.

The acceptable values for the elements of this parameter come from the auditActionTypeEnumSet enumeration. Only the long name of the action type (for example, auditActionTypeEnumSet.writeAuditActionType instead of writeAuditActionType) is accepted. Find the definition of auditActionTypeEnumSet at the relative URL of /schemas/enums/auditActionTypeEnumSet.

See also:

user
Array of strings <= 100 items
Example: user=metasysuser

Filter by list of users. The user property indicates which user initiated the action being audited.

includeDiscarded
boolean

Determines whether discarded audits will be included in the results.

  • true - Return only discarded audits in the response.
  • false - Do not include any discarded audits in the response.
  • missing - Discarded status is ignored; both discarded and non-discarded audits are returned.
equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/audits?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser&includeDiscarded=false&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&space=214f52d1-0c56-4a29-a690-abe5656d1647&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

Gets the first 10 audits.

{
  • "total": 400,
  • "previous": null,
  • "items": [
    ],
  • "effectivePermissions": [
    ],
}

Get audits Deprecated

Retrieves a collection of audits.

Note: This operation is deprecated and may be removed in a future release. To retrieve audits, consider using GET /activities?activityType=audit instead. See List activities

Authorizations:
Bearer-Authentication
query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

originApplication
Array of strings
Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp
metasysEnum: auditOriginAppEnumSet

Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message.

The acceptable values for the elements of this parameter come from the auditOriginAppEnumSet enumeration. Only the long name of the origin application (for example, auditOriginAppEnumSet.deviceManagerAuditOriginApp instead of deviceManagerAuditOriginApp) is accepted. Find the definition of auditOriginAppEnumSet at the relative URL of /schemas/enums/auditOriginAppEnumSet.

See also:

classLevel
Array of strings
Example: classLevel=auditClassesEnumSet.userActionAuditClass
metasysEnum: auditClassesEnumSet

Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose.

The Enabled Audit Level attribute (attributeEnumSet.auditEnabledClasLev) determines which audit levels the system generates. Therefore, be aware that there will be no audits to return if the Enabled Audit Level attribute is set too low to generate audits at the desired class level in this filter. This attribute is set per device (for audits generated on that device).

The acceptable values for the elements of this parameter come from the auditClassesEnumSet enumeration. Only the long name of the class level (for example, auditClassesEnumSet.userActionAuditClass instead of userActionAuditClass) is accepted. Find the definition of auditClassesEnumSet at the relative URL of /schemas/enums/auditClassesEnumSet.

See also:

actionType
Array of strings
Example: actionType=auditActionTypeEnumSet.writeAuditActionType
metasysEnum: auditActionTypeEnumSet

Filter by list of action types. The action type property indicates the user or system action performed.

The acceptable values for the elements of this parameter come from the auditActionTypeEnumSet enumeration. Only the long name of the action type (for example, auditActionTypeEnumSet.writeAuditActionType instead of writeAuditActionType) is accepted. Find the definition of auditActionTypeEnumSet at the relative URL of /schemas/enums/auditActionTypeEnumSet.

See also:

user
Array of strings <= 100 items
Example: user=metasysuser

Filter by list of users. The user property indicates which user initiated the action being audited.

includeDiscarded
boolean

Determines whether discarded audits will be included in the results.

  • true - Return only discarded audits in the response.
  • false - Do not include any discarded audits in the response.
  • missing - Discarded status is ignored; both discarded and non-discarded audits are returned.
equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/audits?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser&includeDiscarded=false&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

Gets the first 10 audits.

{
  • "total": 400,
  • "previous": null,
  • "items": [
    ],
  • "effectivePermissions": [
    ],
}

Get an audit

Retrieves the specific audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/audits/4990ee27-7a0a-4b2b-9b27-279e3f1a060c \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

An audit for an analog value object.

{
  • "id": "6c6ae3dd-c514-423d-bd22-0b48678c5384",
  • "creationTime": "2021-12-10T21:05:53Z",
  • "actionType": "auditActionTypeEnumSet.commandAuditActionType",
  • "activityManagementStatus": "pending",
  • "status": "statusEnumSet.ok",
  • "spaces": [ ],
  • "equipment": [ ],
  • "preData": {
    },
  • "postData": null,
  • "parameters": [
    ],
  • "errorString": null,
  • "user": null,
  • "signature": null,
  • "itemReference": "{hostname}:{deviceHostname}/AV1",
  • "objectName": "Interlock1/AV1",
  • "classLevel": "auditClassesEnumSet.applicationAuditClass",
  • "originApplication": "auditOriginAppEnumSet.interlockAuditOriginApp",
  • "description": "commandIdEnumSet.adjustCommand"
}

Edit an audit

Allows for discarding an audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

Request Body schema: application/json
required
activityManagementStatus
required
string
Value: "discarded"

The new activity management status of the audit.

The only accepted value of this property is discarded because it is the only valid activity management state transition for an audit. Once an audit is discarded, it cannot be changed to any other state.

annotationText
string or null

The annotation to associate with the change of audit state.

Responses

Request samples

Content type
application/json
{
  • "activityManagementStatus": "discarded"
}

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "code": "string",
  • "message": "string",
  • "details": { },
  • "innerError": { },
  • "innerErrors": [
    ]
}

Get audit annotations

Retrieves the collection of annotations available for the specified audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/audits/4990ee27-7a0a-4b2b-9b27-279e3f1a060c/annotations?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Add audit annotation

Adds an annotation to an audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

Request Body schema: application/json
required
text
required
string [ 1 .. 255 ] characters \S

The text of the annotation to create. This must not be null, empty, nor only whitespace. Additionally, any surrounding whitespace will be trimmed.

Responses

Request samples

Content type
application/json
{
  • "text": "Looks okay."
}

List audit users

Retrieves a list of unique usernames from all users present in a currently stored audit. The provided usernames may or may not reflect known users of the current system, but were known when the system recorded an audit for them.

Authorizations:
Bearer-Authentication

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/audits/users \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Get audit counts (PRIVATE)

Gets counts of audits in specified time intervals for a given time period grouped by audit string ids (optionally grouped by specified time interval).

Authorizations:
Bearer-Authentication
query Parameters
auditActions
Array of integers
Example: auditActions=41,42,107,150

Filter by audit strings. auditTrailStringsEnumSet.

The values for this property come from the auditTrailStringsEnumSet.

Find the definition of auditTrailStringsEnumSet at the relative URL of /schemas/enums/auditTrailStringsEnumSet.

Note: This parameter does not follow the standard convention of using symbolic names. You must provide the integer identifier of the members of the set you wish to filter by.

See also:

startTime
required
string <date-time>
Example: startTime=2022-07-21T10:00:00-05:00

Only include results generated on or after this date-time.

endTime
required
string <date-time>
Example: endTime=2022-07-22T09:08:59-05:00

Only include results generated on or before this date-time.

timeInterval
string
Default: "None"
Enum: "None" "Hour" "Day" "Week" "Month"
Example: timeInterval=Hour

A time interval in which audit counts will be grouped by.

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/audits/counts?auditActions=41%2C42%2C107%2C150&startTime=2022-07-21T10%3A00%3A00-05%3A00&endTime=2022-07-22T09%3A08%3A59-05%3A00&timeInterval=Hour' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example
[
  • {
    },
  • {
    }
]

authentication

Operations to get and refresh an access token.

Request access token

Use this to request an access token that can be used for authentication on other API calls.

Request Body schema: application/json
required

Used to supply credentials for login.

username
string

The user name of an account. This can either be a local Metasys account, or an Active Directory account that has been granted access to Metasys. When using an Active Directory account, the value should be in the format {name}@{domain} (for example, jane-doe@mycorp.com).

Note: Only accounts with an Access Type of API can be used to request a token from the REST API.

password
string

The corresponding password of a Metasys account.

Responses

Request samples

Content type
application/json
Example
{
  • "username": "jane-doe",
  • "password": "strongPassword"
}

Response samples

Content type
application/vnd.metasysapi.v5+json

The result includes the access token needed to make requests. (The token in this example has been truncated.)

{
  • "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
  • "expires": "2021-04-22T00:12:18Z"
}

Refresh a token

Use this operation to request a new token before the previous one expires.

Authorizations:
Bearer-Authentication

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/refreshToken \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

The result includes the access token needed to make requests. (The token in this example has been truncated.)

{
  • "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
  • "expires": "2021-04-22T00:12:18Z"
}

Request access token (PRIVATE)

Use this to request a trusted peer access token that can be used for authentication on other API calls. This is intended for one service to call another without having to login as a user.

Request Body schema: application/json
required

Used to supply credentials to request a trusted peer token.

clientId
string

The client id of the service that you are connecting to.

secret
string

The corresponding secret used to verify that you should be granted access.

Responses

Request samples

Content type
application/json
{
  • "clientId": "Metasys.Server",
  • "secret": "9d845ba5-d0c6-4f62-81dd-07b8fe31a68b"
}

Response samples

Content type
application/vnd.metasysapi.v5+json

The result includes the access token needed to make requests. (The token in this example has been truncated.)

{
  • "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
  • "expires": "2021-04-22T00:12:18Z"
}

authentication settings

System settings for authentication services

🛠 Get active directory settings (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Gets the system settings related to Active Directory

Authorizations:
Bearer-Authentication

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/authenticationSettings/activeDirectory \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "activeDirectoryConfiguration": {
    },
  • "serviceAccounts": [ ]
}

🛠 Edit active directory settings (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

undefined

Authorizations:
Bearer-Authentication
Request Body schema: application/json
required
object
Array of objects

Responses

Request samples

Content type
application/json
{
  • "activeDirectoryConfiguration": {
    },
  • "serviceAccounts": [ ]
}

🛠 Get ADFS settings (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Gets the ADFS settings

Authorizations:
Bearer-Authentication

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/authenticationSettings/adfs \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "enabled": false,
  • "ssoEnabled": false,
  • "endPoint": null,
  • "clientId": null
}

🛠 Edit ADFS settings (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

undefined

Authorizations:
Bearer-Authentication
Request Body schema: application/json
required
enabled
boolean
ssoEnabled
boolean
endPoint
string or null
clientId
string or null

Responses

Request samples

Content type
application/json
{
  • "enabled": false,
  • "ssoEnabled": false,
  • "endPoint": null,
  • "clientId": null
}

certificates

Operations related to certificates and signing requests of network devices

Read a certificate signing request (PRIVATE)

Retrieve the binary CSR data for a single device. A successful (200) response provides the CSR in a PEM format.

Note: This endpoint is intended to support application/vnd.metasysapi.v5+json and application/octet-stream MIME types via the Accept header however neither of these are currently supported. Only application/pkcs10 is supported even though it shouldn't be.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

header Parameters
If-None-Match
string
Example: DrIITJxrrFDVYbFrmM41X6xj/v+HlD/QgWuvNeIPCvM=

A previous ETag header value. If the current state of the resource does not match this, then the current resource will be returned. If the current state of the resource does match this value, then the current resource will not be returned and the response will be a 304 (Not Modified).

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/signingRequests/bacnet \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'If-None-Match: DrIITJxrrFDVYbFrmM41X6xj/v+HlD/QgWuvNeIPCvM='

Response samples

Content type

A certificate signing request in PEM format meant for a raw output (a MIME type of application/octet-stream).

-----BEGIN CERTIFICATE REQUEST-----
MIIBlTCCARwCAQIwgZwxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJXSTESMBAGA1UE
BwwJTWlsd2F1a2VlMRkwFwYDVQQKDBBKb2huc29uIENvbnRyb2xzMREwDwYDVQQL
DAhDb250cm9sczEYMBYGA1UEAwwPTUFDMDI0MkFDMTUxNzA2MSQwIgYJKoZIhvcN
AQkBFhVqYWNvYi5wLmhpY2tzQGpjaS5jb20wdjAQBgcqhkjOPQIBBgUrgQQAIgNi
AASv3V9GGmXQqNmTCKIZPy4unQBGPDYG6RzqybRrJO6ZSVTm31y1XYuvFIE0u+I3
NrtpR0DPDCvfDlecQkEpkgB5roIijDh7/ZEKDwQgvc8pvxWVzCv7OQw4OoCK1bd8
SXOgADAKBggqhkjOPQQDAgNnADBkAjBoC8P9g/2r9yS1MR9H4iv/f3uvbzP8PQd3
4PJdATJjZsHWVml1E42DEK5ejQDl6rICMFLNL5Mwf029d9v+/X2UvrZ12TJDC8nx
2ZrcTdE6zw5cyxVwR9xyJ8YqU35iqvsTmA==
-----END CERTIFICATE REQUEST-----

Create certificate signing request (PRIVATE)

Create a new certificate signing request (CSR) for the specified device and CSR parameters. A successful (201) response provides the CSR in a PEM format.

Note: This endpoint is intended to support application/vnd.metasysapi.v5+json and application/octet-stream MIME types via the Accept header however neither of these are currently supported. Only application/pkcs10 is supported even though it shouldn't be.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

Request Body schema: application/json
emailAddress
required
string <email> [ 1 .. 63 ] characters
orgName
required
string [ 1 .. 63 ] characters
orgUnitName
required
string [ 1 .. 63 ] characters
city
required
string [ 1 .. 63 ] characters
stateProvince
required
string [ 1 .. 63 ] characters
country
required
string = 2 characters
domainName
string or null [ 1 .. 47 ] characters

Responses

Request samples

Content type
application/json
{
  • "city": "Milwaukee",
  • "country": "US",
  • "emailAddress": "noreply@jci.com",
  • "orgName": "Johnson Controls",
  • "orgUnitName": "BAS",
  • "stateProvince": "WI",
  • "domainName": "jci.com"
}

Response samples

Content type

A certificate signing request in PEM format meant for a raw output (a MIME type of application/octet-stream).

-----BEGIN CERTIFICATE REQUEST-----
MIIBlTCCARwCAQIwgZwxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJXSTESMBAGA1UE
BwwJTWlsd2F1a2VlMRkwFwYDVQQKDBBKb2huc29uIENvbnRyb2xzMREwDwYDVQQL
DAhDb250cm9sczEYMBYGA1UEAwwPTUFDMDI0MkFDMTUxNzA2MSQwIgYJKoZIhvcN
AQkBFhVqYWNvYi5wLmhpY2tzQGpjaS5jb20wdjAQBgcqhkjOPQIBBgUrgQQAIgNi
AASv3V9GGmXQqNmTCKIZPy4unQBGPDYG6RzqybRrJO6ZSVTm31y1XYuvFIE0u+I3
NrtpR0DPDCvfDlecQkEpkgB5roIijDh7/ZEKDwQgvc8pvxWVzCv7OQw4OoCK1bd8
SXOgADAKBggqhkjOPQQDAgNnADBkAjBoC8P9g/2r9yS1MR9H4iv/f3uvbzP8PQd3
4PJdATJjZsHWVml1E42DEK5ejQDl6rICMFLNL5Mwf029d9v+/X2UvrZ12TJDC8nx
2ZrcTdE6zw5cyxVwR9xyJ8YqU35iqvsTmA==
-----END CERTIFICATE REQUEST-----

Replace certificate signing request (PRIVATE)

Replace the certificate signing request (CSR) for the specified device and CSR parameters. A successful (200) response provides the CSR in a PEM format.

Note: This endpoint is intended to support application/vnd.metasysapi.v5+json and application/octet-stream MIME types via the Accept header however neither of these are currently supported. Only application/pkcs10 is supported even though it shouldn't be.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

header Parameters
If-Match
required
string
Example: 33a64df551425fcc55e4d42a148795d9f25f89d4

A previous ETag header value. If the current state of the resource does not match this value, then the operation will fail. If the current state of the resource does match this value, then the operation will continue.

Request Body schema: application/json
emailAddress
required
string <email> [ 1 .. 63 ] characters
orgName
required
string [ 1 .. 63 ] characters
orgUnitName
required
string [ 1 .. 63 ] characters
city
required
string [ 1 .. 63 ] characters
stateProvince
required
string [ 1 .. 63 ] characters
country
required
string = 2 characters
domainName
string or null [ 1 .. 47 ] characters

Responses

Request samples

Content type
application/json
{
  • "city": "Milwaukee",
  • "country": "US",
  • "emailAddress": "noreply@jci.com",
  • "orgName": "Johnson Controls",
  • "orgUnitName": "BAS",
  • "stateProvince": "WI",
  • "domainName": "jci.com"
}

Response samples

Content type

A certificate signing request in PEM format meant for a raw output (a MIME type of application/octet-stream).

-----BEGIN CERTIFICATE REQUEST-----
MIIBlTCCARwCAQIwgZwxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJXSTESMBAGA1UE
BwwJTWlsd2F1a2VlMRkwFwYDVQQKDBBKb2huc29uIENvbnRyb2xzMREwDwYDVQQL
DAhDb250cm9sczEYMBYGA1UEAwwPTUFDMDI0MkFDMTUxNzA2MSQwIgYJKoZIhvcN
AQkBFhVqYWNvYi5wLmhpY2tzQGpjaS5jb20wdjAQBgcqhkjOPQIBBgUrgQQAIgNi
AASv3V9GGmXQqNmTCKIZPy4unQBGPDYG6RzqybRrJO6ZSVTm31y1XYuvFIE0u+I3
NrtpR0DPDCvfDlecQkEpkgB5roIijDh7/ZEKDwQgvc8pvxWVzCv7OQw4OoCK1bd8
SXOgADAKBggqhkjOPQQDAgNnADBkAjBoC8P9g/2r9yS1MR9H4iv/f3uvbzP8PQd3
4PJdATJjZsHWVml1E42DEK5ejQDl6rICMFLNL5Mwf029d9v+/X2UvrZ12TJDC8nx
2ZrcTdE6zw5cyxVwR9xyJ8YqU35iqvsTmA==
-----END CERTIFICATE REQUEST-----

Delete certificate signing request (PRIVATE)

Clear any existing certificate signing request (CSR) for the specified device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

header Parameters
If-Match
required
string
Example: 33a64df551425fcc55e4d42a148795d9f25f89d4

A previous ETag header value. If the current state of the resource does not match this value, then the operation will fail. If the current state of the resource does match this value, then the operation will continue.

Responses

Request samples

curl --request DELETE \
  --url https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/signingRequests/bacnet \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'If-Match: 33a64df551425fcc55e4d42a148795d9f25f89d4'

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "statusName": "string",
  • "message": "string",
  • "details": { },
  • "innerError": { },
  • "innerErrors": [
    ]
}

Read BACnet/SC certificate (PRIVATE)

Retrieve the raw and/or structured certificate data for a single device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
flatten
boolean
Default: true
Example: flatten=true

Return the certificates as a flat list or as nested trees. When nested, the result items will have an items array property that contains the child certificates.

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/certificates/bacnet?flatten=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

Certificate details as a list. Note that JSON must encode new lines (\n) for the raw property.

{
  • "items": [
    ]
}

Write BACnet/SC certificate (PRIVATE)

Write the raw certificate data for a single device. The data may be a single operational certificate or the entire chain.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

Request Body schema: application/octet-stream
string <binary> (rawCertificate)

Responses

Request samples

Content type
application/octet-stream

A certificate in PEM format.

-----BEGIN CERTIFICATE-----
MIICJjCCAcugAwIBAgIJALlDHY8rFJaRMAoGCCqGSM49BAMCMBoxGDAWBgNVBAMT
D01ldGFzeXMgVGVzdCBDQTAeFw0yMTA0MTkyMjA2MzdaFw0yMjAzMzAxOTQ1MTBa
MH4xHzAdBgkqhkiG9w0BCQEWEHRlc3RAdGVzdEFsbC5jb20xGDAWBgNVBAMTD01B
QzAyNDI3MDM1QUM2RDELMAkGA1UECxMCQkUxDDAKBgNVBAoTA0pDSTEMMAoGA1UE
BxMDTUtFMQswCQYDVQQIEwJXSTELMAkGA1UEBhMCVVMwdjAQBgcqhkjOPQIBBgUr
gQQAIgNiAARei12VLrNFW9ThXWbuP9jjgqumm+qRbYmjRr2Eft09gzcn9fSZyr7g
pmUZVsTeEbzzkAJDDFVobQ4iis5iXD8iAs/h4DkFc5eoXmS5hWGL3n5VPLfE1hCB
D6HZCVGmd/6jeTB3MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgWgMB0GA1UdJQQWMBQG
CCsGAQUFBwMBBggrBgEFBQcDAjAdBgNVHQ4EFgQULuIeIdZBqqIwQvIP4T/RKpWD
GoUwHwYDVR0jBBgwFoAUQTHU+UodcSQ+Yk/8IEaPAjRA+nowCgYIKoZIzj0EAwID
SQAwRgIhAOBqzqlMJtoTvQxH0qx1s6oVY1NvsyXthO9SZlwlYEkeAiEAwyU0/jgU
NaHD0eqyywHZxyQto1vTscCbTJZIuFOVGnk=
-----END CERTIFICATE-----

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "statusName": "string",
  • "message": "string",
  • "details": { },
  • "innerError": { },
  • "innerErrors": [
    ]
}

Delete BACnet/SC certificate (PRIVATE)

Delete the certificate(s) for a single device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
loose
boolean
Default: true
Example: loose=true

If true, indicates that all issuer certificates which are not the authority of the currently active operational certificate should be deleted.

Note: Only true is currently supported.

Responses

Request samples

curl --request DELETE \
  --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/certificates/bacnet?loose=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "statusName": "string",
  • "message": "string",
  • "details": { },
  • "innerError": { },
  • "innerErrors": [
    ]
}

Import BACnet/SC certificates (PRIVATE)

Write a collection of raw certificate data to the devices associated to the included certificates.

Authorizations:
Bearer-Authentication
Request Body schema: application/zip
required

A ZIP file which must contain 1 or more operational certificates and their issuer certificate(s). The issuer certificate(s) may be a separate file or included with each operational certificate (known as a PKCS #7 file).

string <binary>

Responses

Request samples

curl --request POST \
  --url https://metasys-server.example.com/api/v5/networkDevices/certificates/bacnet \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

Import BACnet/SC certificates success response

[
  • {
    },
  • {
    },
  • {
    }
]

controls

Operations on control objects.

Diagrams

Some controls may have a visual representation known as a diagram. While a diagram is a visual representation, it is more importantly the means by which control logic is defined for some types of controls.

A diagram contains 3 general elements - blocks, ports, and connections.

A block generally represents some primitive function, such as an add operation. Most blocks work upon some number of input ports and provide the result via output ports. Blocks may have additional configuration to them as well.

The ports of blocks can be connected via connections to pass values from a source to a destination.

Block Schemas

Every block in a diagram is defined by a schema. A schema defines what the available properties and ports are available on a block. The properties and ports have associated metadata to define value types and value constraints.

A block schema is a JSON Schema, with some custom keywords:

  • sequenceProperties - indicates that all properties defined under it should be generated from a sequence of integer values. Every property name should be a format string which includes {n} as a placeholder to where the sequence number is populated. The source of the sequence numbering is defined by a countSource property, which defines how many properties are currently defined in the instance data that follow a templated sequence. This value should resolve to a property of the block. The schema of the countSource property should always be of type "integer", have a non-negative minimum, and have a maximum.
  • everything from the Object Developers Guide

Diagram Streaming Events

Diagrams may be subscribed to for streaming events by a client. A subscription is established by providing a METASYS-SUBSCRIBE header with the GET operation of a diagram.

See also:

To subscribe to a diagram use the Get diagram operation and include a METASYS-SUBSCRIBE header. The value of this header should be the stream id you received when you opened a stream.

Here are the types of events sent by the diagram subscription along with example data payloads for each.

  • diagram.subscription.established - Indicates when a subscription has been established for the diagram.

    Example Data Payload
    {
      "id": "d7861b6a-d563-5521-a746-a68519cb7651",
      "subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"],
      "message": "Live value subscription successful"
    }
    
  • diagram.subscription.cancelled - Indicates when a subscription has been cancelled for the diagram.

    Example Data Payload
    {
      "id": "d7861b6a-d563-5521-a746-a68519cb7651",
      "subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
      "message": "Live value subscription cancelled"
    }
    
  • diagram.values.update - Indicates a change in value of blocks or ports within the diagram. The first occurrence of this event will include all values in the diagram. Subsequent occurrences will only include values that changed from the previous occurrence.

    Example Data Payload
    {
      "id": "d7861b6a-d563-5521-a746-a68519cb7651",
      "subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"],
      "items": [
        ["8", 2.0],
        ["9", 2.0, { "reliability": "reliabilityEnumSet.writeError" }]
      ]
    }
    

    Each entry in items is a tuple of 2 or 3 values:

    • The first value is the identifier of the diagram entity (a diagram connection). This directly maps to the id property of the diagram entity.
    • The second value is the current value of the diagram entity. The type of this value could be a number, a string (in the case of an enumeration value), or null.
    • The third value is optional and represents any non-normal condition of the current value.

    The first diagram.values.update event payload for a new subscription of a diagram will contain all current values of entities in the diagram. Subsequent events will only contain values that changed from the previous event.

  • diagram.error - Indicates an error occurred during cancelling a subscription.

    Example Data Payload
    {
      "subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
      "message": "Error while cancelling subscription"
    }
    
  • diagram.heartbeat - Indicates that the logic service is alive.

    Example Data Payload
    "ping from logic service @2021-08-04T16:03:23.3771485Z"
    
  • diagram.update - Indicates a change in the structure of the diagram. This event will cause the subscription to be cancelled.

    Example Data Payload
    {
      "id": "d7861b6a-d563-5521-a746-a68519cb7651",
      "subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
      "message": "The diagram has been updated.. Please refresh. Current subscription will be cancelled automatically."
    }
    

Relationship to Objects

An instance of a control is really an instance of an object available at the relative URL of /objects/{objectId}. As a control, the representation of the object is more aligned with control logic in an abstracted manner rather than a more primitive and more complex representation.

Get diagram (INTERNAL)

Retrieves the diagram of the specified control instance.

If the METASYS-SUBSCRIBE header is provided, then an event subscription will be created which will include the events described in Diagrams

Authorizations:
Bearer-Authentication
path Parameters
controlId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the control.

query Parameters
includeSchema
boolean
Default: false

Indicates whether the schema of the diagram should also be returned.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/controls/5a22812f-ec51-4c11-ab4a-fc986f94f008/diagram?includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

Shows the results of a diagram with no blocks or connections.

{}

Replace diagram (INTERNAL)

Replaces the diagram of the specified control instance.

Possible Errors

There are a variety of errors that are possible when attempting to update a diagram. Every known error that can be determined will be communicated in a response. The error response is hierarchical such that the top-most errors describe generalized issues while inner-most errors describe specific issues. Each error is intended to be self-descriptive with accompanying details.

  • api.diagram:error.saveFailed

    The save failed. innerError or innerErrors will have more information

  • api.diagram:error.schemaFailure

    The payload did not validate against the schema.

  • api.diagram:error.diagramSchemaFailure

    The diagram did not validate against the schema.

  • api.diagram:error.invalidSchemaUrl

    A block's schema URL is invalid or doesn't reference a known block type.

  • api.diagram:error.blockSchemaFailure

    A block did not validate against its schema.

  • api.diagram:error.connectionSchemaFailure

    A connection did not validate against its schema.

  • api.diagram:error.unboundReferences

    The configured object reference for an Input Reference or Output Reference could not be resolved.

  • enum.core:statusEnumSet.writeAccessDeniedSecurity

    The user is not authorized to modify the diagram.

  • api.diagram:error.unauthorizedExistingDiagram

    The user is not authorized to modify the existing diagram.

  • api.diagram:error.unauthorizedRequestDiagram

    The user is not authorized to control some references in the new diagram.

  • api.diagram:error.duplicateId

    The same id is defined multiple times in the diagram.

  • api.diagram:error.circularLogic

    An unsupported circular loop has been defined in the diagram.

  • api.diagram:error.ioAttributes

    A general wrapper for any errors related to Input Attributes and Output Attributes.

  • api.diagram:error.ioThresholdExceeded

    The diagram contains more than the maximum allowed inputs or outputs.

  • api.diagram:error.duplicateIOBlockName

    The diagram contains duplicate Input Attribute and Output Attribute names.

  • api.diagram:error.duplicateIOAttribute

    The diagram contains duplicate Input Attribute and Output Attribute identifiers.

  • api.diagram:error.connection

    A general wrapper for any errors related to a connection.

  • api.diagram:error.portDoesNotExist

    The port referenced by a connection's source or destination is not defined.

  • api.diagram:error.portsCannotBeFromSameBlock

    A connection's source and destination cannot be from the same block.

  • api.diagram:error.delayConnectedToOutputTypeBlock

    A Delay block should not be connected to an Output Reference or Output Attribute.

  • api.diagram:error.priorityNotSupported

    A connection does not support priority when connected to anything other than Output Reference.

  • api.diagram:error.portDirectionInvalidForConnectionEndpoint

    The source of a connection cannot be an input port of a block and the destination of a connection cannot be an output port of a block.

  • api.diagram:error.block

    A general wrapper for any errors related to a block.

  • api.diagram:error.invalidEnum

    An enumeration value is not valid.

  • api.diagram:error.duplicatePortInSubSystem

    A System block cannot define a port as both being an input and an output.

  • api.diagram:error.portDoesNotExistInSubSystem

    A System block exposes a port which is not defined.

  • api.diagram:error.inPortIsNotWritableInSubSystem

    A System block exposes a input port which is not writable.

  • api.diagram:error.limitsCountMismatchInSequencer

    A Sequencer block doesn't have the same number of make limit values as break limit values.

  • api.diagram:error.limitsDoesNotMatchOutputsInSequencer

    A Sequencer block must have the same number of make & break limit values as the number of outputs. If proactive is true, then the expected count of limit values should be one less than the number of outputs.

  • api.diagram:error.limitsNotInAscendingOrderInSequencer

    A Sequencer block must have make & break limit values in ascending order.

  • api.diagram:error.breakIsGreaterThanMakeInSequencer

    A Sequencer block must have break limits which are less than their corresponding make limit of the same stage.

  • api.diagram:error.makeIsGreaterThanBreakInSequencer

    A Sequencer block must have make limits which are less than the break limit of the previous stage.

  • api.diagram:error.duplicateModeSelectionInMux

    A Multiplexor (MUX) block cannot use the same mode enumeration value multiple times.

Authorizations:
Bearer-Authentication
path Parameters
controlId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the control.

Request Body schema: application/json
required

The desired blocks and connections of the diagram. This is the same structure as the item property from the GET /diagram response.

required
object (Diagram)

A set of blocks and connections which make up an instance of programmable control logic.

Responses

Request samples

Content type
application/json
Example

A diagram with no blocks or connections.

{
  • "item": {
    }
}

Response samples

Content type
application/vnd.metasysapi.v5+json

Shows the response of a replace diagram request which had no item property.

{
  • "statusName": "api.diagram:error.saveFailed",
  • "message": "Diagram save failed. Please see innerError(s) for more information.",
  • "innerError": {
    }
}

Delete control subscription (INTERNAL)

Deletes a subscription to a control resource.

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Responses

Request samples

curl --request DELETE \
  --url https://metasys-server.example.com/api/v5/controls/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Get palette (INTERNAL)

Retrieves a palette, which defines the available types of blocks available to diagramming.

Authorizations:
Bearer-Authentication
path Parameters
paletteId
required
string
Example: 01443cbc-d65e-4666-85d5-484a3b1f4f21

The identifier of the palette.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/controls/palettes/01443cbc-d65e-4666-85d5-484a3b1f4f21 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

An LCT palette (this is only a partial example).

{}

Get palette block (INTERNAL)

Retrieves the schema for a specific block type.

Authorizations:
Bearer-Authentication
path Parameters
paletteId
required
string
Example: 01443cbc-d65e-4666-85d5-484a3b1f4f21

The identifier of the palette.

blockDefinitionId
required
string
Examples:
  • text - Text
  • system-6441be80-52c2-4e40-ae60-655f3319c435 - LCT Sub-System

The ID of the block definition to get the schema for. The ID is the last portion of the schemaUrl and $id properties of a block definition.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/controls/palettes/01443cbc-d65e-4666-85d5-484a3b1f4f21/text \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

The Text Block definition on the LCT palette.

{
  • "title": "Text",
  • "description": "The schema for a text block instance",
  • "type": "object",
  • "properties": {
    },
  • "required": [
    ],
  • "additionalProperties": false,
  • "views": [
    ]
}

enumerations

Operations on enumerations

List enumerations (INTERNAL)

Enumerations are an important data type used by Metasys®. A single enumeration is used to define a set of values a property can have and each value includes a localized string to describe itself.

query Parameters
enumType
string
Default: "all"
Enum: "all" "twoState" "multiState" "custom"
Examples:
  • enumType=all - Return all
  • enumType=twoState - Return two-state only
  • enumType=multiState - Return multi-state only
  • enumType=custom - Return custom only

The type of enumerations to return.

minNumberOfStates
integer
Example: minNumberOfStates=4

Filter the result to include only those multi-state and custom enumerations with at least the specified minNumberOfStates. This parameter is ignored if enumType is not specified as custom or multiState. Note: For various reasons, some multi-state enums have more or less members than their defined number of states.

includePermissions
boolean
Default: false

Include effective permissions for the client with respect to enumerations.

header Parameters
Accept-Language
Array of strings
Example: en-US, de-De

The language to use for display text of enumeration name and members. If no language is specified the client's default language as specified in their user profile will be used.

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/enumerations?enumType=all&minNumberOfStates=4&includePermissions=false' \
  --header 'Accept-Language: en-US, de-De'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Create an enumeration (INTERNAL)

Create a custom enumeration with members of your choice

Authorizations:
Bearer-Authentication
Request Body schema: application/json
required

New enumeration

required
object

An enumeration

Responses

Request samples

Content type
application/json
{
  • "item": {
    }
}

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Get an enumeration (INTERNAL)

Get an enumeration

path Parameters
id
required
string
Examples:
  • writePriorityEnumSet - The Write Priority enumeration
  • displayPrecisionEnumSet - The Display Precision enumeration
  • enumerationSetNamesEnumSet - The Enumeration Set Names enumeration. (The names of all enumerations)

The enumeration to retrieve. To see a list of all possible enumeration ids see the GET /enumerations operation.

query Parameters
includeSchema
boolean

Include the schema of the enumeration. The schema will tell you which members of the enumeration (if any) are editable.

includePermissions
boolean

Include the effective permissions the client has with respect to this enumeration.

header Parameters
Accept-Language
Array of strings
Example: en-US, de-De

The language to use for display text of enumeration name and members. If no language is specified the client's default language as specified in their user profile will be used.

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/enumerations/writePriorityEnumSet?includeSchema=false&includePermissions=false' \
  --header 'Accept-Language: en-US, de-De'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example
{}

Edit an enumeration (INTERNAL)

Can be used to modify the name of the enumeration and the values of any of the member strings. Cannot be used to add/remove members.

Authorizations:
Bearer-Authentication
path Parameters
id
required
string
Example: customEnumSet30001

The enumeration to edit.

Request Body schema: application/json
required
required
object

Responses

Request samples

Content type
application/json
Example
{
  • "item": {
    }
}

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Replace an enumeration (INTERNAL)

Replace an enumeration with a new definition. You can not replace a two-state enumeration with a multiple-state enumeration. Nor can you replace a multiple-state enumeration with a two-state enumeration.

Authorizations:
Bearer-Authentication
path Parameters
id
required
string
Example: customEnumSet30001

The enumeration to replace

Request Body schema: application/json
required
object

An enumeration

Responses

Request samples

Content type
application/json
{
  • "item": {
    }
}

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Delete an enumeration (INTERNAL)

Delete an enumeration. Only custom enumerations may be deleted.

Authorizations:
Bearer-Authentication
path Parameters
id
required
string
Example: customEnumSet30001

The enumeration to delete.

Responses

Request samples

curl --request DELETE \
  --url https://metasys-server.example.com/api/v5/enumerations/customEnumSet30001 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

equipment

This section describes the operations you can perform on equipment. Equipment is a broad term for anything that makes a building run, including boilers, chillers, air handling units, lights, meters, and security systems. Use equipment operations to get equipment instances and to list equipment points. Apply filters, sorting, and paging to further refine the results.

Get equipment hosted by a network device

Retrieves the collection of equipment instances hosted by the specified network device or its children. A network device is considered to host an equipment if the equipment defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get equipment instances

Retrieves a collection of equipment instances.

Authorizations:
Bearer-Authentication
query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of equipment instances.

Get a single equipment instance

Retrieves the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get equipment served by an equipment instance

Retrieves the equipment served by the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get equipment that serve an equipment instance

Retrieves the collection of equipment that serve the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: 04d68394-3415-4813-b5ec-43d840deee38

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/equipment/04d68394-3415-4813-b5ec-43d840deee38/upstreamEquipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

List equipment points

Retrieves the collection of points that are defined by the specified equipment instance. Each point contains a mapping to an attribute on an object.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "shortName"
Enum: "category" "-category" "equipmentName" "-equipmentName" "isDisplayData" "-isDisplayData" "shortName" "-shortName"
Example: sort=shortName

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/points?page=1&pageSize=100&sort=shortName' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of equipment points

{}

Get equipment serving a space

Retrieves the collection of equipment that serve the specified space.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

health

A set of reports related to cyber-health

🛠 Get accounts report (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Get accounts report

Authorizations:
Bearer-Authentication

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/health/reports/accounts \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "accountTypeCounts": {
    },
  • "policyViolationCounts": {
    }
}

🛠 Get devices report (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Get devices report

Authorizations:
Bearer-Authentication

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/health/reports/devices \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "pre52": {
    },
  • "post52Pre81": {
    },
  • "post81": {
    },
  • "expiringCerts": {
    },
  • "expiredCerts": {
    }
}

network-devices

This section describes the operations you can perform on network devices. Network devices are physical devices such as coordinators and routers that are required for communication between hardware on a computer network. Use network device operations to get, list, and delete network devices. Apply filters, sorting, and paging to further refine the results.

List network devices

Retrieves a collection of network devices.

Authorizations:
Bearer-Authentication
query Parameters
objectType
string
Example: objectType=bacnetIntegrationClass
metasysType: enum
metasysEnum: objectTypeEnumSet

The type of network device to return.

The objectType query parameter cannot be used in conjunction with the classification query parameter.

The acceptable values for this parameter come from the objectTypeEnumSet enumeration. Only the long name of the object type (for example, objectTypeEnumSet.bacnetIntegrationClass instead of bacnetIntegrationClass) is accepted. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

classification
Array of strings
Items Enum: "device" "integration" "server" "controller"
Examples:
  • classification=device&classification=server&classification=controller - Only devices (excludes integrations)
  • classification=device - Only supervisory engines
  • classification=server&classification=device - Servers and supervisory engines

The classification to filter devices on. One or more values are supported.

The classification query parameter cannot be used in conjunction with the objectType query parameter.

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/networkDevices?objectType=bacnetIntegrationClass&page=1&pageSize=100&sort=name&classification=device&classification=server&classification=controller' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of network devices.

{}

Get a single network device

Retrieves the specified network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A single network device.

{}

Deletes a network device

Deletes an engine or a server which is a child device of the site director. Cannot be used to delete controllers, integrations, or the site director.

Note: The device must be offline for the operation to succeed.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

Responses

Request samples

curl --request DELETE \
  --url https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

List network device children

Retrieves the collection of network devices that are children of the specified network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/networkDevices?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of network devices.

{}

Batch request for network devices (PRIVATE)

Allows for batching multiple requests to many network devices.

The following operations relative to a network device are supported:

Relative Path GET POST PUT PATCH DELETE
{networkDeviceId}/certificates/bacnet
{networkDeviceId}/signingRequests/bacnet

This batch operation supports up to 1000 requests at a time.

Implementation Notes

The certificate signing request body in responses is base64 encoded PEM content, which is different from the non-batch PEM response.

The schema of the request body is inconsistent with other batch paths. See GIV-108568.

Authorizations:
Bearer-Authentication
Request Body schema: application/json
required

A collection of individual requests relative to the networkDevices path. All requests will use the same HTTP method and should be for the same resource type relative to the network device.

object or string

An optional shared body for all requests. This will be ignored for any individual request which defines its own body.

required
Array of objects non-empty

An array of individual requests.

Responses

Request samples

Content type
application/json
Example

Create certificate signing requests for multiple devices with the same parameters.

{}

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

Create certificate signing requests for multiple devices with the same parameters.

{
  • "responses": [
    ]
}

List network devices hosting an equipment instance

Retrieves the collection of network devices that host the specified equipment instance, along with the parents of those network devices. A network device hosts an equipment when the equipment defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of network devices.

{}

List network devices serving a space

Retrieves the collection of network devices that serve the specified space. A space serves a network device when any equipment instance serving the space defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/networkDevices?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of network devices.

{}

object queries

A set of built-in queries on objects

Get objects in alarm (INTERNAL)

Retrieves a list of objects for the well known alarm query.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the object. This must be a supervisory device object id for a well known query.

query Parameters
cursor
integer
Example: cursor=243

A handle to next page of data

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/alarm?cursor=243&pageSize=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get all of the objects that are in alarm for the device. The object id needs to be a supervisory device.

{
  • "items": [
    ]
}

Get disabled objects (INTERNAL)

Retrieves a list of objects for the well known disabled query.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the object. This must be a supervisory device object id for a well known query.

query Parameters
cursor
integer
Example: cursor=243

A handle to next page of data

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/disabled?cursor=243&pageSize=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get all of the objects that are disabled.

{}

Get offline objects (INTERNAL)

Retrieves a list of objects for the well known offline query.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the object. This must be a supervisory device object id for a well known query.

query Parameters
cursor
integer
Example: cursor=243

A handle to next page of data

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/offline?cursor=243&pageSize=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get all of the objects that are offline.

{}

Get overridden objects (INTERNAL)

Retrieves a list of objects for the well known operator override query.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the object. This must be a supervisory device object id for a well known query.

query Parameters
cursor
integer
Example: cursor=243

A handle to next page of data

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/operatorOverride?cursor=243&pageSize=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get all of the objects that are in operator override.

{
  • "next": null,
  • "items": [
    ]
}

Get out of service objects (INTERNAL)

Retrieves a list of objects for the well known out of service query.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the object. This must be a supervisory device object id for a well known query.

query Parameters
cursor
integer
Example: cursor=243

A handle to next page of data

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/outOfService?cursor=243&pageSize=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get all of the objects that are out of service.

{}

Get overridden N2 device objects (INTERNAL)

Retrieves a list of objects for the well known supervisory override query.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the object. This must be a supervisory device object id for a well known query.

query Parameters
cursor
integer
Example: cursor=243

A handle to next page of data

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/supervisoryOverride?cursor=243&pageSize=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get all of the objects that are in supervisory override.

{
  • "next": null,
  • "items": [
    ]
}

Get objects with a trouble status (INTERNAL)

Retrieves a list of objects for the well known trouble query.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the object. This must be a supervisory device object id for a well known query.

query Parameters
cursor
integer
Example: cursor=243

A handle to next page of data

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/trouble?cursor=243&pageSize=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get all of the objects that have a trouble status.

{}

object trees

An object tree is a hierarchical structure of objects. Metasys exposes trees in its user interfaces (and this API) to provide a means of discovery and navigation. The built-in tree is the "all items" tree which is also called the network tree. Users can also create their own custom hierarchies of trees. These are called interchangeably user defined trees or user views.

This section of the API provides operations to discover and retrieve the various object trees defined in the system.

List object trees (INTERNAL)

Returns a list of all the navigation trees for objects. This includes the "all-items" tree as well as the user defined trees (user views). The list will contain all of the object trees on the system but the effectivePermissions.canRead property in the response payload will list only those trees that the user can read.

Authorizations:
Bearer-Authentication

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/objects/trees \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Get user view (INTERNAL)

This operation fetches the specified tree.

This operation differs from Get an object in that it actually returns the tree, whereas Get an object returns the object representation of the user view. The object representation contains metadata about the user view (for example, its name, objectCategory and itemReference).

Note: The response to this operation does not include modification constraints. If you wish to see modification constraints for the objects call GET /trees/{treeId}/objects or GET /trees/{treeId}/objects/{objectId}/objects

See also:

  • [List tree objects][#operation/gettreeobjects]
  • [List tree object children][#operation/gettreeobjectchildren]
Authorizations:
Bearer-Authentication
path Parameters
treeId
required
string
Example: c0d8ebe7-d246-5bc3-a16c-c1aa19589c45

The unique object identifier of the tree to retrieve. To discover the set of available treeId values see List object trees.

query Parameters
includePermissions
boolean
Default: false
Example: includePermissions=true

Include effective permissions of the current user with respect to the objects in this tree.

includeConditions
boolean
Default: false
Example: includeConditions=true

Include a condition section in the payload that lists any objects that have been deleted. (In the future this section could be used to indicate any other useful condition flags.)

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/trees/c0d8ebe7-d246-5bc3-a16c-c1aa19589c45?includePermissions=true&includeConditions=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

objects

This section describes the operations you can perform on objects. Objects are self-contained functional items in the Metasys system, for a full definition refer to the Metasys System Glossary. Use objects operations to list, create, edit, and delete objects. Apply filters, sorting, and paging to further refine the results. Some operations accept subscriptions, see Change of Value Subscriptions.

(INTERNAL) Some operations have limitations, see Operation Restrictions.

Batch Subscriptions And Async Operations

Change of Value Subscriptions

Subscribe for change of value (COV) events to receive updates when attribute values change. Currently, subscriptions are available for Get attribute value operations (individual and batch).

Subscribing

To subscribe for COV events, complete the following steps:

  1. Open a stream with the Get a stream operation. Take note of the stream ID.
  2. Use one of the following operations and include a METASYS-SUBSCRIBE header with the stream ID:

Note: Any filters added to the original GET operation also apply to the event subscription.

Unsubscribing

To unsubscribe from a COV event, complete the following steps:

  1. Get the METASYS-SUBSCRIPTION-LOCATION from the subscribe operation response.
  2. Issue a Delete COV subscription request to METASYS-SUBSCRIPTION-LOCATION.

See also:

Events

COV Events : There are three event types sent by the COV subscription: heartbeat, update, and notification.

  • object.values.heartbeat - A heartbeat event is sent to show that the subscription is still alive. A heartbeat is a JSON string with the current UTC date time in ISO 8601 format and is sent every 30 seconds.

  • object.values.update - The client receives an update event when an attribute value changes. This payload is similar in structure as the payload returned by Get attribute value, but also includes id and itemReference of the object to provide context for the attribute in question. The overall schema for this payload is identical to the Get an object schema (except this payload has no effectivePermissions property). The payload excludes the schema for the attribute by default, but it can be optionally included by using the includeSchema flag on the initial subscription request.

subscriptionIds
required
Array of strings <uuid> [ items <uuid > ]

Subscription IDs that the update applies to

required
object

New value information for the subscribed attributes with additional identifying information for the object the update applies to.

object (condition)

This property contains condition flags (if any are set) for the properties of item. If none of the properties have any condition flags set, then condition will not be included in the response or it will be empty.

schema
object

A JSON schema that describes the properties of the item property

{
  • "subscriptionIds": [
    ],
  • "item": {
    },
  • "condition": {
    }
}
  • object.values.notification - A notification event is sent when a value has changed but the value is not included in the payload. This happens for some values that are not simple scalar values. You can use this event as a trigger to reread the attribute. In the example, even though the payload does not include the current value, you know which object this is for (based on id and itemReference), and you know it is the overrideExpirationTime attribute based on the attribute property.
subscriptionIds
required
Array of strings <uuid> [ items <uuid > ]

Subscription IDs that the notification applies to

required
object

Identifying information for the object the notification applies to which a client can use to read the new value of the attribute.

attribute
required
string
metasysType: enum
metasysEnum: attributeEnumSet

The attribute the notification applies to.

The values for this property come from the attributeEnumSet enumeration. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

object (condition)

This property contains condition flags (if any are set) for the properties of item. If none of the properties have any condition flags set, then condition will not be included in the response or it will be empty.

{
  • "subscriptionIds": [
    ],
  • "item": {
    },
  • "condition": {
    },
  • "attribute": "attributeEnumSet.overrideExpirationTime"
}

Object Ordering Async Operation

(PRIVATE) Ordering Events : There is one event types sent by the asynchronous ordering operation: update.

  • objects.ordering.update - The client receives an update event when an object order changes. The data payload within the event includes the resulting ordering. If the resulting ordering matches the requested ordering then the payload will include a status property with the value statusEnumSet.ok, otherwise the status will indicate an error:

    • statusEnumSet.operationCompletionError - There was an error updating the ordering.
    • statusEnumSet.deviceOffline - The update could not happen because the device was offline.
self
required
string

The relative path to the new ordering for the child objects under parentId (NOT YET IMPLEMENTED)

subTreeUrl
required
string

The relative path to the child objects under parentId

parentId
required
string

Parent ID that the update applies to

status
required
object

status can be any of statusEnumSet.ok, statusEnumSet.deviceOffline or statusEnumSet.OperationCompletionError

subscriptionIds
required
Array of strings <uuid> [ items <uuid > ]

Subscription IDs that the update applies to

{
  • "self": "objects/f576ecbe-6ee2-5da5-a9b5-a89841b05cdc/objects/ordering",
  • "subTreeUrl": "objects/f576ecbe-6ee2-5da5-a9b5-a89841b05cdc/objects",
  • "parentId": "f576ecbe-6ee2-5da5-a9b5-a89841b05cdc",
  • "status": "statusEnumSet.ok",
  • "subscriptionIds": [
    ]
}

Asynchronous operations (PRIVATE)

This section contains private notes about private asynchronous operations.

The following operations support asynchronous operations

None at this time.

Calling operations asynchronously

To call an operation asynchronously it must accept the METASYS-CALL-ASYNC header. Then follow these steps.

  1. Open a stream with the Get a stream operation. Take note of the stream ID.
  2. Invoke your operation and include a METASYS-CALL-ASYNC header with the stream ID.

Cancelling an asynchronous operation

To cancel a running asynchronous operation, complete the following steps:

  1. Take note of the value of the METASYS-SUBSCRIPTION-LOCATION header included in the response to the asynchronous operation request. (This location represents a temporary subscription resource that is created for streaming the results of the operation.)

  2. Delete the subscription resource. For example

    DELETE /objects/streams/{streamId}/subscriptions/{subscriptionsId}
    

See also:

Operation Restrictions (INTERNAL)

There are restrictions on certain operations that are not otherwise communicated by the API. These are documented in the following requirements and restrict the creation of certain objects and the writing of certain attributes.

Object Type Forbidden Create Forbidden Attribute Writes
Interlock [G4R-4055][] [G4R-4054][] - actionTbl1, actionTbl2, commandsPriority, source
MCO [G4R-4057][] [G4R-4056][] - actionTbl1, commandsPriority
DLLR n/a [G4R-4053][] - loadList
System n/a [G4R-4060][] - attributeInfo, fileName, logicSequence

The attributes of the System object should be marked readOnly in the schema and a CR (G4CR-8324) is written up for that. The other restrictions are intended to be removed in a future release.

List objects

Returns the root object of the tree and, optionally, its children. The root object is the site object. The default response is a tree representation. Set flatten=true to flatten the tree into a list representation. The number of levels returned depends on the value of the depth parameter. To get just the root of the tree use a depth of 0. Values of depth greater than 1 are not allowed on this endpoint.

Authorizations:
Bearer-Authentication
query Parameters
depth
integer [ 0 .. 1 ]
Default: 1
Example: depth=1

The depth of the tree to return. The provided value is ignored if pathTo, objectType, or classification are specified.

flatten
boolean
Default: false

A value of true indicates the response payload should be a flat list. A value of false (the default) indicates the response payload should be a tree with child objects nested under their parent object. While this parameter influences the shape of the response, it does not affect the content. The same set of objects is returned no matter the value of this parameter.

includeExtensions
boolean
Default: false

A value of true indicates that extension objects should be included in the result. A value of false (the default) indicates that they should not be included.

This parameter is ignored if pathTo is specified.

pathTo
string
Example: pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a

This parameter causes the response to contain the object specified by this parameter, the root object, and the objects in between.

If this parameter is specified, then depth and includeExtensions are ignored.

includeInternal
boolean
Default: false
visibility: internal

(INTERNAL) A value of true indicates that internal objects should be included in the result. A value of false (the default) indicates that they should not be included.

includeEffectivePermissions
boolean
Default: false
Example: includeEffectivePermissions=true

Include the effectivePermissions property in the response payload. This property describes which objects in the response the current user can view, modify or delete.

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects?depth=1&flatten=false&includeExtensions=false&pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a&includeInternal=false&includeEffectivePermissions=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

The objects are returned in a tree structure. Child objects are nested under their parents.

{}

Create object

Creates a new object. Several things are needed to successfully create an object. You must know

  • the type of object you want to create
  • if that object type is supported in the location you want to create it
  • what properties can be set on that type of object when creating it
  • what properties are required to be set.

Find the complete list of object types with the operation GET /schemas/enums/objectTypeEnumSet. To determine the specific set of objects that can be created in a location use List supported child types (GET /objects/{objectId}/supportedChildTypes). To discover what object properties can be set and which are required when creating an object use Get a schema for an object type (GET /schemas/objectTypes/{objectType})

See also:

Authorizations:
Bearer-Authentication
Request Body schema: application/json
required
parentId
required
string

The ID of the parent object. The new object will be created under this object.

localUniqueIdentifier
required
string <= 32 characters ^[^\x00-\x1F\x7F\x22#'*,.\/:<>?@\[\\\]|]+$

A string that is locally unique within the context of the parent object for identifying the new object. This string will be the last component of the itemReference of the newly created object. For example, assume you have a folder with an itemReference of adx:oas/Programming. Then you create an AV with a local unique identifier of ZN-3-T within that folder. The newly created object will have an itemReference of adx:oas/Programming.ZN-3-T.

The value must not contain any control characters or any of the following characters: " # ' * , . / : < > ? @ [ \ ] |

objectType
required
string
metasysType: enum
metasysEnum: objectTypeEnumSet

The type of object to create.

The values for this property come from the objectTypeEnumSet enumeration. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

item
object

The item object is where you set the properties of the newly created object. Which properties can be set and their data types can be discovered by using the Get schema for object type operation.

This property may or may not be required depending on the object you are creating. Some objects have defaults for all properties and require nothing to be set when creating them. Others have required properties that must be set at creation time.

Responses

Request samples

Content type
application/json
Example

This request body creates a new object of type objectTypeEnumSet.avClass under a folder with an identifier of 82b6f2d5-6fed-5074-b611-94dd40028312 with a locally unique identifier of ZN-3-SETPT. The properties on the new object are name, description, objectCategory, minPresValue and maxPresValue.

{
  • "parentId": "82b6f2d5-6fed-5074-b611-94dd40028312",
  • "localUniqueIdentifier": "ZN-3-SETPT",
  • "objectType": "objectTypeEnumSet.avClass",
  • "item": {
    }
}

List child objects

Returns the specified object and optionally one or more levels of the tree under the object. The default response is a tree representation. Set flatten=true to flatten the tree into a list representation.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 767d8af0-163f-552c-ba37-a884466075f9

Specifies the root of the subtree to return for this request. The objectId is the identifier of the object to retrieve (optionally along with 1 or more levels of descendants).

query Parameters
depth
integer >= -1
Default: 1
Example: depth=1

The depth of the tree to return. For typical usage, a value or 1 or 2 is recommended. Use -1 for maximum depth.

The provided value is ignored if pathTo, objectType, or classification are specified.

flatten
boolean
Default: false

A value of true indicates the response payload should be a flat list. A value of false (the default) indicates the response payload should be a tree with child objects nested under their parent object. While this parameter influences the shape of the response, it does not affect the content. The same set of objects is returned no matter the value of this parameter.

includeExtensions
boolean
Default: false

A value of true indicates that extension objects should be included in the result. A value of false (the default) indicates that they should not be included.

This parameter is ignored if pathTo is specified.

pathTo
string
Example: pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a

This parameter filters the response down to just containing the object specified by this parameter, the object specified by objectId in the path, and the objects in between.

If this parameter is specified, then depth, includeExtensions, objectType and classification are ignored.

objectType
string
Examples:
  • objectType=objectTypeEnumSet.avClass - Analog Value Object Type
  • objectType=objectTypeEnumSet.bvClass - Binary Value Object Type
  • objectType=objectTypeEnumSet.mvClass - Multiple Value Object Type
metasysType: enum
metasysEnum: objectTypeEnumSet

Type of objects to include in the response. This parameter may be repeated. To search for all AV and AI objects one would specify /objects?type=objectTypeEnumSet.avClass&type=objectTypeEnumSet.aiClass.

The use of this parameter overrides depth to -1 and includeExtensions to true.

It is an error to specify this parameter if classification is specified.

The response will include the specified object, the objects that match the objectType for the given depth and any objects in between (like folders and devices).

The acceptable values for this parameter come from the objectTypeEnumSet enumeration. It is acceptable to use the short name of the object type (for example, avClass instead of objectTypeEnumSet.avClass) because the enumeration set is known from context. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

classification
string
Enum: "object" "device" "integration" "controller" "point" "site" "navList" "extension" "folder" "reference" "server" "archive"
Examples:
  • classification=object - Any object not classified by one of the other classification values
  • classification=device - An object that represents a supervisory controller
  • classification=controller - An object that represents a field controller

Filter objects to those with the specific classification. The use of this parameter overrides depth to -1 and includeExtensions to true. It is an error to specify this parameter if objectType is specified.

includeInternal
boolean
Default: false
visibility: internal

(INTERNAL) A value of true indicates that internal objects should be included in the result. A value of false (the default) indicates that they should not be included.

includeEffectivePermissions
boolean
Default: false
Example: includeEffectivePermissions=true

Include the effectivePermissions property in the response payload. This property describes which objects in the response the current user can view, modify or delete.

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/767d8af0-163f-552c-ba37-a884466075f9/objects?depth=1&flatten=false&includeExtensions=false&pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a&objectType=objectTypeEnumSet.avClass&classification=object&includeInternal=false&includeEffectivePermissions=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

The objects are returned in a tree structure. Child objects are nested under their parents.

{}

Change order of objects (PRIVATE)

(NOT IMPLEMENTED) This is a design for an operation not yet implemented.

This endpoint changes the ordering of objects under a specified object.

This is an asynchronous operation which must be invoked with a valid METASYS-CALL-ASYNC header (obtained by using the Get a stream operation). If the request was valid, then when the operation completes an objects.ordering.update event will be sent over the stream.

The data payload within the event includes the resulting ordering. If the resulting ordering matches the requested ordering then the payload will include a status property with the value statusEnumSet.ok, otherwise the status will indicate an error:

  • statusEnumSet.operationCompletionError - There was an error updating the ordering.
  • statusEnumSet.deviceOffline - The update could not happen because the device was offline.
Example Data Payload
{
  "self": "https://{hostname}/api/v5/objects/767d8af0-163f-552c-ba37-a884466075f9/objects/ordering",
  "subTreeUrl": "https://{hostname}/api/v5/objects/767d8af0-163f-552c-ba37-a884466075f9/objects",
  "parentId": "767d8af0-163f-552c-ba37-a884466075f9",
  "status": "statusEnumSet.ok",
  "subscriptionIds": ["538f00be-5788-4f68-a60e-45a14356c7ef"]
}

The subTreeUrl is the link to retrieve the result items.

Implementation details: If one or more object writes fail resulting in an ordering that does not match the requested ordering, then the status shall be statusEnumSet.operationCompletionError. If one or more writes fail but the resulting ordering does match the requested ordering the status should be statusEnumSet.ok. How might this happen? Assume I have the ordering [a, b, c, d] and I request to change it to [a, b, d, c]. I assume we attempt to write each object. Now if the writes to a and b fail, presumably that's fine since their values aren't changing. Note: Since this seems extremely unlikely (the only scenario we are aware where this would fail is when the device is offline) I'm okay with skipping the check in first implementation.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 767d8af0-163f-552c-ba37-a884466075f9

Specifies a parent object.

header Parameters
METASYS-CALL-ASYNC
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b
visibility: private

(PRIVATE) If present, instructs the server that the operation should be invoked asynchronously. The value of this header is a stream id obtained by opening a stream with Get a stream. The operation will then return an http response immediately while the operation runs in the background. The result(s) of this operation will then be sent in one or more events over the specified stream instead of in the body of the http response.

See also:

Request Body schema: application/json
required
items
required
Array of strings

An array of object identifiers. Each entry is an identifier of one of the child objects. The order of the identifiers in the array shall indicate the new ordering of the child objects.

It is acceptable to send an array of identifiers that is a subset of all of the child object identifiers. In that case, the specified identifiers shall be ordered first. The identifiers that are not included in the request will maintain their relative order with respect to each other but shall come after all of the specified identifiers.

For example, if the current ordering is [a, b, c, d] and the request specifies an ordering of [c, b] the resulting ordering is [c, b, a, d] (Actual identifiers are not single characters.).

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Get object id Deprecated

Use Lookup object identifier instead.

Finds the object identifier (the id property of an object) for the object with the specified fully qualified reference (fqr).

Authorizations:
Bearer-Authentication
query Parameters
fqr
required
string
Examples:
  • fqr=adx:adx - An example of a site director fqr
  • fqr=adx:nae23/Programming.AV1 - An example of an analog value object fqr
format: fully-qualified-reference

The fully qualified reference of an object. It refers to an object's itemReference property.

Fully qualified references use characters that must be escaped when used as query parameters. Most HTTP libraries do this for you automatically. However, if you are using curl or PowerShell where you specify the full URL yourself you may need to be aware. For example, here is the URL to use with curl for a reference of oas:oas/Programming.AV3: https://{hostname}/api/v5/objectIdentifiers?fqr=oas%3Aoas%2FProgramming.AV3

(PRIVATE) This parameter is actually optional. The partialReference parameter may be specified instead of this parameter.

partialReference
string
Examples:
  • partialReference=adx - An example of a site director partial reference
  • partialReference=nae23/Programming.AV1 - An example of an analog value object partial reference
visibility: private

(PRIVATE) A partial reference of an object.

A partial reference differs from a fully qualified reference in that the site portion of the fully qualified reference is omitted.

Like a fully qualified reference, a partial reference may use characters that must be escaped when used as a query parameter. (See the example in the description of the fqr parameter.)

This parameter cannot be specified if fqr is specified.

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objectIdentifiers?fqr=adx%3Aadx&partialReference=adx' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
"32cfddc0-411f-5b9e-9a6d-442cb62fecbb"

Lookup object identifier

Finds the object identifier (the id property of an object) for the object with the specified fully qualified reference (fqr).

Authorizations:
Bearer-Authentication
query Parameters
fqr
required
string
Examples:
  • fqr=adx:adx - An example of a site director fqr
  • fqr=adx:nae23/Programming.AV1 - An example of an analog value object fqr
format: fully-qualified-reference

The fully qualified reference of an object. It refers to an object's itemReference property.

Fully qualified references use characters that must be escaped when used as query parameters. Most HTTP libraries do this for you automatically. However, if you are using curl or PowerShell where you specify the full URL yourself you may need to be aware. For example, here is the URL to use with curl for a reference of oas:oas/Programming.AV3: https://{hostname}/api/v5/objectIdentifiers?fqr=oas%3Aoas%2FProgramming.AV3

(PRIVATE) This parameter is actually optional. The partialReference parameter may be specified instead of this parameter.

partialReference
string
Examples:
  • partialReference=adx - An example of a site director partial reference
  • partialReference=nae23/Programming.AV1 - An example of an analog value object partial reference
visibility: private

(PRIVATE) A partial reference of an object.

A partial reference differs from a fully qualified reference in that the site portion of the fully qualified reference is omitted.

Like a fully qualified reference, a partial reference may use characters that must be escaped when used as a query parameter. (See the example in the description of the fqr parameter.)

This parameter cannot be specified if fqr is specified.

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/identifiers?fqr=adx%3Aadx&partialReference=adx' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
"32cfddc0-411f-5b9e-9a6d-442cb62fecbb"

Get an object

Objects support one or more views. By default, this operation gets the default view of an object. For many objects this is the Focus View (identifier viewNameEnumSet.focusView). To see the list of views an object supports see List Views (/objects/{objectId}/views). To get a different view of an object specify a value for the viewId parameter.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

  • List Views for information on retrieving the view collection of an object.
Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
viewId
string
Examples:
  • viewId=viewNameEnumSet.focusView - Focus View
  • viewId=viewNameEnumSet.diagnosticView - Diagnostic View
metasysEnum: viewNameEnumSet

The view to retrieve.

This parameter is optional and if it is not specified the default view for the object will be returned. For many objects this is the Focus view (focusView).

The acceptable values for this parameter come from the viewNameEnumSet enumeration. It is acceptable to use the short name of the view (for example, focusView instead of viewNameEnumSet.focusView) because the enumeration set is known from context. Find the definition of viewNameEnumSet at the relative URL of /schemas/enums/viewNameEnumSet.

See also:

includeSchema
boolean

Every object can have a unique schema. Set this parameter to true to include the schema for this object in the response payload.

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb?viewId=viewNameEnumSet.focusView&includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

This is an example of an AV object without a schema. Notice that the presentValue is 105 but the maxPresValue is set to 100. This results in the presentValue attribute going unreliable. This can be seen in the condition object where presentValue has a reliability value of reliabilityEnumSet.unreliableHigh. We can also see that the current priority for presentValue is set to writePriorityEnumSet.priorityCriticalEquipment.

{}

Edit an object

This operation modifies one or more attributes of an object. Note: attributes must be updated in whole. For example, if you wish to modify an attribute of metasysType struct which is modelled as a JSON object you must include all elements of the struct. It is undefined what might happen if you do not. The write could fail, the non-mentioned members may get their default value or something else. This applies to any attribute that has a JSON type of array or object. The entire attribute value must be written even if you only wish to change one part of the value.

The request body contains an item property which contains one or more properties and their new values.

The attributes of an object (and their schemas) can be discovered by looking at the different views of an object or by requesting all of the attributes.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Request Body schema: application/json
required
item
object

The attributes to update.

Responses

Request samples

Content type
application/json
Example
{
  • "item": {
    }
}

Delete an object

Deletes the specified object.

Not all objects can be deleted (not even by an administrator). Examine the effectivePermissions of an object to determine if it can be deleted by the current user.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples

curl --request DELETE \
  --url https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

List the views of an object

Objects support one or more views. Each view of an object contains a logical grouping of the object's attributes. This operation lists the collection of views that an object has.

Each entry in the response contains the id of a view, and also the absolute URL used to request that view. Use Get an object (/objects/{objectId}) to request a specific view by specifying the desired id for the viewId query parameter.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
includeSchema
boolean

Set this parameter to true to include a schema in the response.

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/views?includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

Get public view (INTERNAL)

Returns a set of attributes for an object. The attributes returned are considered public information for any authenticated user and therefore no special privileges are required to call this operation.

One of the attributes returned by this operation (for many objects) is the default attribute (defaultAttribute). If the object has a default attribute then the attribute named by the defaultAttribute property is also included in the response. For example, the analog value (AV) object has a defaultAttribute of attributeEnumSet.presentValue so presentValue is included in the public view of an AV.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
includeSchema
boolean

Every object can have a unique schema. Set this parameter to true to include the schema for this object in the response payload.

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/publicView?includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

This is an example of a public view for an AV object with schema included.

{
  • "objectType": "objectTypeEnumSet.avClass",
  • "item": {
    },
  • "schema": {
    },
  • "effectivePermissions": {
    },
  • "condition": { }
}

List attributes of an object

Returns an object payload with a JSON schema that contains all of the properties of the object. Each property entry contains only a partial schema for that property. (To discover the full schema of an attribute use /objects/{objectId}?includeSchema=true or /objects/{objectId}/attributes/{attrId}?includeSchema=true

The item section of the payload will contain at most one attribute, the defaultAttribute. The item section will be completely missing if the object does not have a default attribute.

There will be no views or condition sections like a typical object payload.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/attributes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example
{
  • "item": {
    },
  • "schema": {
    }
}

Get attribute value

Returns an object payload containing the specified attribute. Invoke this operation with a valid METASYS-SUBSCRIBE header to create a subscription for changes to that attribute, rather than returning a value. The current value and any updates to the attribute are instead sent over the specified stream.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

attributeId
required
string
Examples:
  • presentValue - The Present Value
  • itemReference - The Fully Qualified reference
metasysEnum: attributeEnumSet

The attribute to read.

The acceptable values for this parameter come from the attributeEnumSet enumeration. Only the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) is accepted. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

query Parameters
includeSchema
boolean

Set this parameter to true to include a schema in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/attributes/presentValue?includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example
{
  • "item": {
    },
  • "condition": {
    },
  • "schema": {
    }
}

List commands

Returns a payload that lists all of the commands that an object supports. Each command entry has an invokeUrl property, which is the URL needed to invoke the command. In addition, each command entry has a commandBodySchema property, which is a JSON schema that describes the acceptable payload for the command. Commands are invoked using the HTTP method PUT along with the invokeUrl and acceptable body.

Note: Some objects, such as multi-state values (MV) and binary values (BV), may list a command that has a commandSet property and a property named aggregateCommand with a value of true instead of invokeUrl. This commandSet lists one or more commands. This entry is not a true command but rather provides a hint to graphical user interfaces on how they may want to group the commands of the commandSet under one command name. For example, an MV object lists a command with the identifier commandIdEnumSet.adjustCommand. This is not an actual command on an MV. Instead the actual commands that could be used to present this command in a UI are listed in the commandSet and they have identifiers like commandIdEnumSet.multistate0Command. The Metasys User Interface displays all of these commands as a single adjust command with the titles of the individual commands as the parameter to send.

Licensing Restrictions

Requires Monitoring and Commanding API license.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/commands \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example
{
  • "items": [
    ],
  • "effectivePermissions": {
    }
}

Send command

Used to send a command to an object. The payloads of commands differ, but they share some similarities. To learn the specifics of the commands of an object use List commands.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

commandId
required
string
Example: adjustCommand
metasysEnum: commandIdEnumSet

The identifier of the command to send.

The acceptable values for this parameter come from the commandIdEnumSet enumeration. It is acceptable to use the short name of the command identifier (for example, adjustCommand instead of commandIdEnumSet.adjustCommand) because the enumeration set is known from context. Find the definition of commandIdEnumSet at the relative URL of /schemas/enums/commandIdEnumSet.

See also:

Request Body schema: application/json
required

The body of a command is defined by the commandBodySchema. The commandBodySchema is a property of every command returned by the List commands operation.

priority
string (write-priority-enum-set)
Enum: "writePriorityEnumSet.priorityNone" "writePriorityEnumSet.priorityManualEmergency" "writePriorityEnumSet.priorityFireApplications" "writePriorityEnumSet.priority3" "writePriorityEnumSet.priority4" "writePriorityEnumSet.priorityCriticalEquipment" "writePriorityEnumSet.priorityMinimumOnOff" "writePriorityEnumSet.priorityHeavyEquipDelay" "writePriorityEnumSet.priorityOperatorOverride" "writePriorityEnumSet.priority9" "writePriorityEnumSet.priority10" "writePriorityEnumSet.priorityDemandLimiting" "writePriorityEnumSet.priority12" "writePriorityEnumSet.priorityLoadRolling" "writePriorityEnumSet.priority14" "writePriorityEnumSet.prioritySchedulingOst" "writePriorityEnumSet.priorityDefault"
metasysType: enum
metasysEnum: writePriorityEnumSet
parameters
Array of any >= 0 items
annotation
string

Responses

Request samples

Content type
application/json
Example

This body is used with the adjust command of an Analog Value (AV). It sends the value 72.5 along with an annotation about why the command was invoked. The URL for this command is /objects/{objectId}/commands/adjustCommand

{
  • "parameters": [
    ],
  • "annotation": "Increase the set point to make it warmer."
}

Response samples

Content type
application/vnd.metasysapi.v5+json
"Success"

List supported child types

Many objects support nested objects. The obvious examples of this are folder objects and device objects. Less obvious examples include objects like analog value and multi-state value objects (which can have child objects like integrations). This operation lists the types of objects that can be created under an object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/supportedChildTypes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

The supported child types of a folder.

[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

List object equipment points

Retrieves all equipment points mapped to attributes of this object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "shortName"
Enum: "category" "-category" "equipmentName" "-equipmentName" "isDisplayData" "-isDisplayData" "shortName" "-shortName"
Example: sort=shortName

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/points?page=1&pageSize=100&sort=shortName' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Batch operations

This operation is used to invoke multiple operations in a single HTTP request. Often a batch request is more efficient than sending each individual operation in its own HTTP request.

In this version of the API, the only objects related operation that can be used in a batch is Get attribute value.

If this operation is invoked with a valid METASYS-CALL-ASYNC header it will cause a temporary subscription to be created for the attributes in the request and rather than returning any values, the current values and any updates to the attributes will be sent over the specified stream.

Licensing Restrictions

Requires Monitoring and Commanding API license.

(INTERNAL) In addition to Get attribute value, internal clients may also use Change order of objects and Lookup object identifier. All of the operations in a batch must be the same. You cannot mix Get attribute value with Change order of objects order and/or Lookup object identifier.

(INTERNAL) The Change order of objects operation supports both synchronous and asynchronous calling. METASYS-CALL-ASYNC header is required for async version. If the header is not included, this will be considered as synchronous operation and the API will return the synchronous response only. The async version of Change order of objects will send one objects.ordering.update event per sub-request. The payload for the event will match the payload defined in the Change order of objects operation.

(PRIVATE) Asynchronous version of change of order of objects implementation details

A batch request to change object ordering follows the schema for this operation.

Click to see example request
{
  "method": "PATCH",
  "requests": [
    {
      "id": "1",
      "relativeUrl": "3f8c1e32-4504-5d0a-9d8e-b695b059e272/objects/ordering",
      "body": {
        "items": [
          "56d85c80-2741-5d4f-8f97-02877dd2c0e6",
          "54c74311-4492-5f17-8caa-6ab69619402d"
        ]
      }
    }
  ]
}

Just like the single version of object ordering, each request should have synchronous error checking performed: duplicated child ids, invalid child ids, malformed request. (This could be done by delegating the call to the single versions or in some other way if that's more efficient.)

If the overall batch request is well formed and has at least one sub-request that is valid, then the HTTP response should return a status of 200 . Each sub-response that corresponds to a valid sub-request should have a status of 202 (Accepted) with a null body (The body property is required but null is allowed as an option). The sub-requests that are not valid should return sub-responses with error payloads following the schema already defined for this batch operation:

  • Include appropriate status code
    • 400 (Bad Request) if the sub-request includes duplicate ids or invalid id (and other bad requests that are identified)
    • 400 (Bad Request) if the parentId is invalid(parent id doesn't exist or provided guid is not valid parent)
  • Include body
    • top level property error is required.
    • statusName should be provided (find a suitable value from statusEnumSet, if possible)
    • message should be provided (provide a suitable english message)
    • details are optional but should be provided if more details are required. See the error guidelines when developing the errors as eventually all errors will be converted to the standard. Make this job easier on the future maintainers by designing good payloads now that are hopefully easily converted to the standard.

Here's an example that shows a response to one valid request and one invalid request.

Click to see example response
{
    "requests": [
    {
        "id": "2",
        "status": 202,
        "body": null
    }
    {
        "id": "3",
        "status": 400,
        "body": {
        "error": {
            "statusName": "api:error.parentObjectNotFound",
            "message": "Parent id not found",
            "details": "Object not found: 7ef86382-5cab-57cd-865c-de485916f587"
        }
        }
    }
    ]
}

The message string was chosen because it appears to be our standard error message for all 400 errors. The details provide a user with more information on what was wrong. The api:error.parentObjectNotFound value was chosen for statusName because it's display string is "Object not found"

If the overall batch request is malformed or has no valid sub-requests then the HTTP response should return a 400 status code. The existing schema for a 400 response is simply a string. Provide as informative of a string as possible. (Test with payloads of wrong type, without method, without requests, with every item in requests having errors. )


(PRIVATE) Synchronous version of change of order of objects implementation details

A batch request to change object ordering follows the schema for this operation. Note: Async header should not be passed.

Click to see example request
{
  "method": "PATCH",
  "requests": [
    {
      "id": "1",
      "relativeUrl": "3f8c1e32-4504-5d0a-9d8e-b695b059e272/objects/ordering",
      "body": {
        "items": [
          "56d85c80-2741-5d4f-8f97-02877dd2c0e6",
          "54c74311-4492-5f17-8caa-6ab69619402d"
        ]
      }
    }
  ]
}

Just like the single version of object ordering, each request should have synchronous error checking performed: duplicated child ids, invalid child ids, malformed request. (This could be done by delegating the call to the single versions or in some other way if that's more efficient.)

If the overall batch request is well formed and all the sub-requests are valid, then the HTTP response should return a status of 200 . Each sub-response that corresponds to a valid sub-request should have a status of 202 (Accepted) with a null body (The body property is required but null is allowed as an option).

Error scenarios are same as async version of Change order of Objects.

Here's an example that shows a response to one valid request and one invalid request.

Click to see example response
{
    "requests": [
    {
        "id": "2",
        "status": 202,
        "body": null
    }
    {
        "id": "3",
        "status": 400,
        "body": {
        "error": {
            "statusName": "api:error.parentObjectNotFound",
            "message": "Parent id not found",
            "details": "Object not found: 7ef86382-5cab-57cd-865c-de485916f587"
        }
        }
    }
    ]
}

The message string was chosen because it appears to be our standard error message for all 400 errors. The details provide a user with more information on what was wrong. The api:error.parentObjectNotFound value was chosen for statusName because it's display string is "Object not found"

If the overall batch request is malformed or has no valid sub-requests then the HTTP response should return a 400 status code. A 400 response follows the standard error message schema. (Test with payloads of wrong type, without method, without requests, with every item in requests having errors. )


(INTERNAL) Lookup object identifier implementation details

A batch request to lookup object identifier follows the schema for this operation.

Click to see example request
{
  "method": "GET",
  "requests": [
    {
      "id": "1",
      "relativeUrl": "identifiers?fqr=adx:nae23/Programming.AV1"
    },
    {
      "id": "2",
      "relativeUrl": "identifiers?fqr=adx:nae23/Programming.AV2"
    }
  ]
}

Just like the single version of lookup object identifier, each request should have error checking performed: duplicated child ids, invalid child ids, malformed request. (This could be done by delegating the call to the single versions or in some other way if that's more efficient.)

If the overall batch request is well formed and all the sub-requests are valid, then the HTTP response should return a status of 200 . Each sub-response that corresponds to a valid sub-request should have a status of 200 (OK) with a object identifier as string body.

Error scenarios are same as single version of lookup object identifier.

Here's an example that shows a response to one valid request and one invalid request.

Click to see example response
{
    "requests": [
      {
          "id": "1",
          "status": 200,
          "body": "1817c63a-a043-5231-bf07-bb51c83db8e8"
      }
      {
          "id": "2",
          "status": 400,
          "body": {
            "message": "Invalid FQR."
          }
      }
    ]
}

The message string is the reason why the request is failed.

If the overall batch request is malformed or has no valid sub-requests then the HTTP response should return a 400 status code. A 400 response follows the standard error message schema. (Test with payloads of wrong type, without method, without requests, with every item in requests having errors. )


See also:

Authorizations:
Bearer-Authentication
header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

METASYS-CALL-ASYNC
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b
visibility: private

(PRIVATE) If present, instructs the server that the operation should be invoked asynchronously. The value of this header is a stream id obtained by opening a stream with Get a stream. The operation will then return an http response immediately while the operation runs in the background. The result(s) of this operation will then be sent in one or more events over the specified stream instead of in the body of the http response.

See also:

Request Body schema: application/json
required
method
required
string
Enum: "GET" "PATCH"

The HTTP method to use for each request. This property is restricted to GET for this version of the API since Get attribute value is the only operation supported in a batch.

(INTERNAL) The method PATCH is also supported for internal operations.

required
Array of objects non-empty

A collection of entries that represent the operations to invoke.

Responses

Request samples

Content type
application/json
Example

This example shows a request body that will read the presentValue and status from 3 different objects using sequential numbers as request identifiers.

This example shows the use of sequential numeric values used as request identifiers but any unique strings can be used.

{
  • "method": "GET",
  • "requests": [
    ]
}

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

This example shows the response to a read multiple attributes request. Each operation response is uniquely identified by the corresponding identifier (id) from the request.

{
  • "responses": [
    ]
}

🛠 Create multiple objects (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

This is a bulk operation that creates one or more objects.

comments: Originally available at v2. May have issues as its design was never reviewed by architects. It was created to support the bulk creation of mapper objects after a discover process was done. However, it is not constrained to create only mapper objects. For example, MUI uses it to create extensions on mapper objects as part of the discovery and creation process.
Authorizations:
Bearer-Authentication
Request Body schema: application/json
required
Array
parentId
required
string

The ID of the parent object. The new object will be created under this object.

localUniqueIdentifier
required
string <= 32 characters ^[^\x00-\x1F\x7F\x22#'*,.\/:<>?@\[\\\]|]+$

A string that is locally unique within the context of the parent object for identifying the new object. This string will be the last component of the itemReference of the newly created object. For example, assume you have a folder with an itemReference of adx:oas/Programming. Then you create an AV with a local unique identifier of ZN-3-T within that folder. The newly created object will have an itemReference of adx:oas/Programming.ZN-3-T.

The value must not contain any control characters or any of the following characters: " # ' * , . / : < > ? @ [ \ ] |

objectType
required
string
metasysType: enum
metasysEnum: objectTypeEnumSet

The type of object to create.

The values for this property come from the objectTypeEnumSet enumeration. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

item
object

The item object is where you set the properties of the newly created object. Which properties can be set and their data types can be discovered by using the Get schema for object type operation.

This property may or may not be required depending on the object you are creating. Some objects have defaults for all properties and require nothing to be set when creating them. Others have required properties that must be set at creation time.

Responses

Request samples

Content type
application/json

This shows a request to create two mapper objects.

[
  • {
    },
  • {
    }
]

Response samples

Content type
application/vnd.metasysapi.v5+json
[
  • {
    },
  • {
    }
]

Modify COV subscription (PRIVATE)

Modify a COV subscription by replacing the set of attributes you are subscribed to with a new set of attributes.

How COV works? please check Batch Subscriptions And Async Operations

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Request Body schema: application/json
required

Used to convey the desired subscription.

required
Array of objects

A collection of object id and attribute name that are requested for subscription.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/vnd.metasysapi.v5+json

This example shows the response to a modify subscription with multiple objects and attributes request. first operation returns status of 202 signifying it was accepted. second operation returned with status a 400 to indicate an object not found issue, third operation returned with status a 400 to indicate an attribute not found issue, fourth operation returned with status a 401 to indicate an attribute not authorized issue and last operation returned with status a 400 to indicate multiple errors issue with the request.

{
  • "responses": [
    ]
}

Delete a COV subscription (PRIVATE)

Deletes a COV subscription by subscriptionId.

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Responses

Request samples

curl --request DELETE \
  --url https://metasys-server.example.com/api/v5/objects/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

schemas

A collection of JSON schemas for describing enumerations and object types.

Get enumeration

This operation retrieves the specified enumeration as a JSON schema. The path of this operation appears in several schemas of object payloads.

To get a list of all enumerations fetch the enumerationSetNamesEnumSet:

GET /schemas/enums/enumerationSetNamesEnumSet

See also:

Authorizations:
Bearer-Authentication
path Parameters
enumId
required
string
Examples:
  • writePriorityEnumSet - The write priority enumeration
  • displayPrecisionEnumSet - The display precision enumeration
  • enumerationSetNamesEnumSet - The set of all sets
metasysType: enum

The enumeration to retrieve.

The acceptable values for this parameter come from the enumerationSetNamesEnumSet enumeration. It is acceptable to use the short name of the value (for example, writePriorityEnumSet instead of enumerationSetNamesEnumSet.writePriorityEnumSet) because the enumeration set is known from context. Find the definition of enumerationSetNamesEnumSet at the relative URL of /schemas/enums/enumerationSetNamesEnumSet.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/schemas/enums/writePriorityEnumSet \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example
{
  • "title": "Write Priority",
  • "setId": 1,
  • "oneOf": [
    ]
}

Get object type schema

This endpoint retrieves a schema for a specific objectType. The schema describes the properties that can be set when creating an object of the specific type.

Authorizations:
Bearer-Authentication
path Parameters
objectType
required
string
Examples:
  • objectTypeEnumSet.avClass - AV
  • objectTypeEnumSet.bvClass - BV
  • objectTypeEnumSet.mvClass - MV
metasysEnum: objectTypeEnumSet

The type of object

The acceptable values for this parameter come from the objectTypeEnumSet enumeration. It is acceptable to use the short name of the object type (for example, avClass instead of objectTypeEnumSet.avClass) because the enumeration set is known from context. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

query Parameters
parentId
required
string
Example: parentId=2993aed9-5765-5641-889c-40ec968c8a82

The object under which this new object will be created.

extendedProperty
string
Examples:
  • extendedProperty=attributeEnumSet.presentValue - Present Value
  • extendedProperty=attributeEnumSet.reliability - Reliability
metasysEnum: attributeEnumSet

The attribute to extend.

Indicates which attribute of the parent object the extension should be linked to. Used only for extension objects (like alarm extensions).

The acceptable values for this parameter come from the attributeEnumSet enumeration. It is acceptable to use the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) because the enumeration set is known from context. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/schemas/objectTypes/objectTypeEnumSet.avClass?parentId=2993aed9-5765-5641-889c-40ec968c8a82&extendedProperty=attributeEnumSet.presentValue' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

This schema describes the properties that can be configured when creating an object of the type avClass.

{
  • "schema": {
    },
  • "views": [
    ]
}

Get object type identification information (PRIVATE)

This operation is used to suggest values for identification properties for the next object created in a specific location of a specific type. The properties in question are name and localUniqueIdentifier. (The localUniqueIdentifier isn't a true object property but it is a query parameter used when creating an object and the value is used to generate the itemReference property of an object.)

Note: there is no guarantee that the suggested values are still available at the time a client decides to use them to create a new object.

Note: For field controller objects, additional properties may also be returned in addition to name and localUniqueIdentifier.

Authorizations:
Bearer-Authentication
path Parameters
objectType
required
string
Examples:
  • objectTypeEnumSet.avClass - AV
  • objectTypeEnumSet.bvClass - BV
  • objectTypeEnumSet.mvClass - MV
metasysEnum: objectTypeEnumSet

The type of object

The acceptable values for this parameter come from the objectTypeEnumSet enumeration. It is acceptable to use the short name of the object type (for example, avClass instead of objectTypeEnumSet.avClass) because the enumeration set is known from context. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

query Parameters
parentObjectId
required
string
Example: parentObjectId=b3ca663c-36c1-584f-9462-83d7b3d0349d

An object ID that specifies the location in which a new object is intended to be created. The response payload will then contain identification values that are valid for that location.

extendedProperty
string
Examples:
  • extendedProperty=attributeEnumSet.presentValue - Present Value
  • extendedProperty=attributeEnumSet.reliability - Reliability
metasysEnum: attributeEnumSet

The attribute to extend.

Indicates which attribute of the parent object the extension should be linked to. Used only for extension objects (like alarm extensions).

The acceptable values for this parameter come from the attributeEnumSet enumeration. It is acceptable to use the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) because the enumeration set is known from context. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/schemas/objectTypes/objectTypeEnumSet.avClass/identification?parentObjectId=b3ca663c-36c1-584f-9462-83d7b3d0349d&extendedProperty=attributeEnumSet.presentValue' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

This payload includes a schema that describes the name and localUniqueIdentifier properties and includes a default value for each. This default value for localUniqueIdentifier will always be unique for the given location at the time it is requested.

{
  • "schema": {
    }
}

site

NOTE: The scope of this group of operations is under development and may change at any time.

This section describes the operations you can perform in the context of a site. A site represents a BAS installation at a given location, which may be a single building or multiple buildings. Use site operations to get a semantic model of the entire site.

Get a RDF model (INTERNAL)

Gets the explicit semantic knowledge facts of the site. A fact is an explicit statement, or RDF triple, that has been defined for the site.

In contrast, an inferred fact is a derived statement or piece of knowledge based on explicit facts and ontologies from which the explicit facts are associated to. Inferred facts of the site will not be included in the response of this operation. You will need to obtain the referenced ontologies from their available locations and apply your own set of inference rules in ways that are appropriate for your usage.

Note: The response to this operation may not reflect the latest state of the site if changes have recently been made or the site is actively undergoing changes. This operation will be delayed in providing the latest information until a sufficient quiet period has elapsed or active changes have occurred for a long period of time.

Authorizations:
Bearer-Authentication

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/site/rdf \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
text/turtle
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix data: <http://data.jci.com/data#> .
@prefix jcb: <http://ontologies.jci.com/bacnetObjectModel#> .
@prefix jc: <http://ontologies.jci.com/core#> .
data:975b6588-2bca-5823-b3d6-4c0261b338e3 a jc:Supervisory_Controller;
                                        jcb:itemReference "{hostname}:{deviceHostname}";
                                        rdfs:label "My Engine";
                                        jcb:objectType 8;
                                        jcb:objectInstance 1 .

spaces

Operations on space-related resources.

Get spaces served by a network device

Retrieves the collection of spaces served by the specified network device. A space is served by a network device when any equipment instance serving the space defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/spaces?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of spaces.

{}

Get spaces served by an equipment instance

Retrieves the collection of spaces served by the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/spaces?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of spaces.

{}

Get spaces

Retrieves a collection of spaces.

Authorizations:
Bearer-Authentication
query Parameters
type
string
Example: type=spaceTypesEnumSet.building
metasysType: enum
metasysEnum: spaceTypesEnumSet

Type of space to return.

The acceptable values for this parameter come from the spaceTypesEnumSet enumeration. Only the long name of the space type (for example, spaceTypesEnumSet.building instead of building) is accepted. Find the definition of spaceTypesEnumSet at the relative URL of /schemas/enums/spaceTypesEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/spaces?type=spaceTypesEnumSet.building&page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of spaces.

{}

Get a single space

Retrieves the specified space.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of spaces.

{}

Get space children

Retrieves the collection of spaces that are located within the specified space.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/spaces?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of spaces.

status-indicators

Operations for managing subscriptions to status information for network devices and trees.

Overview

Clients may subscribe to several different types of status information, including:

  • device summary is a high level overview of the entire site. It provides a list of all non ok statuses occurring on each network device, grouped by network device.

  • device details provides a list of all objects with non ok status for a single network device of interest.

  • tree details provides a list of all objects with non ok status for a single tree of interest.

The device summary is used by the Metasys User Interface (MUI) to overlay status indicators (icons) on the unexpanded Building Network tree. When a user expands a network device, MUI subscribes for device details for that device. The device details allow MUI to overlay status indicators on the child objects of that network device. When a user expands a different network device, three things happen:

  1. The former network device of interest has its object hierarchy collapsed.
  2. The device details for that former network device of interest are unsubscribed.
  3. The device details for the new network device of interest are subscribed.

This is an example of a well behaved client, because device details are not subscribed before they are needed and device details are unsubscribed when they are no longer needed.

Tree details is very similar to device details, except that the scope of the subscription is for a tree (formerly called "User Views" in the Site Management Portal).

Both device details and tree details employ the concepts of rank and propagates. Rank is the severity of the status, with a higher rank being more severe. When multiple statuses apply, Metasys user interfaces show the one with the highest rank. Propagates is a hint as to how to apply a status to the hierarchy. For example, if a field controller connected to a network device goes offline (objectStatusEnumSet.osOffline), then that status would be accompanied with a hint to propagate down to all children of that field device (propagates: down). These hints help the event message be succinct and not have to include an entry for each child object. Propagation is up for objectStatusEnumSet.osLowAlarm, to indicate there is some object in an alarm state on this network device. And finally, sometimes there is no propagation. Such is the case for objectStatusEnumSet.osInactive.

Streaming Events

The following events (with accompanying examples) are available for status indicators:

  • statusIndicators.subscription.cancelled - Indicates when a subscription has been cancelled by the system. The subscription has removed and no more updates will arrive for this subscription. Try to subscribe again, but if the problem persists, please contact to your system administrator.

    Example
    {
      "subscriptionIds": ["07606e13-e0f2-4f2c-898a-3745bdfcf9a7"]
    }
    
  • statusIndicators.networkDeviceSummary.update - Indicates a change in device summary status.

    Example
    {
      "subscriptionIds": ["07606e13-e0f2-4f2c-898a-3745bdfcf9a7"],
      "items": [
        // an "item" for each network device on the site
        // note: due to Streaming event size limits, entire update may be split across multiple events
        {
          "id": "guid of device",
    
          // Most severe non-OK status amongst all objects on the network device
          //  (excluding any offline field devices) or defaults to objectStatusEnumSet.osNormal.
          "summarizedStatus": "objectStatusEnumSet.osLowAlarm",
    
          // List of all non-OK statuses for objects on the network device
          "objectStatuses": [
            "objectStatusEnumSet.osOffline",
            "objectStatusEnumSet.osLowAlarm",
            "objectStatusEnumSet.osHighWarning",
            "objectStatusEnumSet.osInactive"
          ]
        }
      ]
    }
    
  • statusIndicators.networkDeviceDetails.update - Indicates a change in network device detail status.

    Example
    {
      "subscriptionIds": ["07606e13-e0f2-4f2c-898a-3745bdfcf9a7"],
      "items": [
        // an "item" for each supervisory device on the site
        // note: due to Streaming event size limits, entire update may be split across multiple events
        {
          "id": "guid of device",
          "objects": [
            {
              // one "object" for each non-OK object on the supervisory device
              "id": "guid of object 1",
              "objectStatus": "objectStatusEnumSet.osInactive",
              "propagates": "none",
              "rank": 1
            },
            {
              "id": "guid of object 2",
              "objectStatus": "objectStatusEnumSet.osLowAlarm",
              "propagates": "up", // up: ancestor nodes
              "rank": 30
            },
            {
              "id": "guid of object 3",
              "objectStatus": "objectStatusEnumSet.osOffline",
              "propagates": "down", // down: child nodes
              "rank": 112
            }
          ]
        }
      ]
    }
    
  • statusIndicators.treeDetails.update - Indicates a change in tree detail status.

    Example
    {
      "subscriptionIds": ["07606e13-e0f2-4f2c-898a-3745bdfcf9a7"],
      "total": 2,
      "items": [
        // an "item" for each tree
        // note: due to Streaming event size limits, entire update may be split across multiple events
        {
          "id": "guid of tree (user view)",
          "objects": [
            {
              // one "object" for each non-OK object in the tree
              "id": "guid of object 1",
              "objectStatus": "objectStatusEnumSet.osInactive",
              "propagates": "none",
              "rank": 1
            },
            {
              "id": "guid of object 2",
              "objectStatus": "objectStatusEnumSet.osLowAlarm",
              "propagates": "up", // up: ancestor nodes
              "rank": 30
            },
            {
              "id": "guid of object 3",
              "objectStatus": "objectStatusEnumSet.osOffline",
              "propagates": "none", // field controller offline doesn't propagate in user views
              "rank": 112
            }
          ]
        }
      ]
    }
    
  • statusIndicators.heartbeat - Affirms subscription(s) that are still active.

    Example
    {
      "subscriptionIds": ["07606e13-e0f2-4f2c-898a-3745bdfcf9a7"],
      "message": "ping from status indicator service @2021-08-04T16:03:23.3771485Z"
    }
    

Create a status indicator subscription (PRIVATE)

Create a subscription to network device summary, detailed status of network device(s) and detailed status of tree(s).

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

Request Body schema: application/json
required

Used to convey the desired subscription.

networkDeviceSummary
boolean

Indicate if network device summary information is desired.

networkDeviceDetails
Array of strings

Array of network device identifiers to subscribe for status details.

treeDetails
Array of strings

Array of tree identifiers to subscribe for status details.

Responses

Request samples

Content type
application/json
Example
{
  • "networkDeviceSummary": true,
  • "networkDeviceDetails": [
    ],
  • "treeDetails": [
    ]
}

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

The request body contains an unrecognized network device id.

{
  • "statusName": "api:error.deviceNotFound",
  • "message": "Could not find network device by ID.",
  • "details": {
    }
}

Replace (modify) a status indicator subscription (PRIVATE)

Modify a subscription to network device summary, detailed status of network device(s) and detailed status of tree(s).

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Request Body schema: application/json
required

Used to convey the desired subscription.

networkDeviceSummary
boolean

Indicate if network device summary information is desired.

networkDeviceDetails
Array of strings

Array of network device identifiers to subscribe for status details.

treeDetails
Array of strings

Array of tree identifiers to subscribe for status details.

Responses

Request samples

Content type
application/json
Example
{
  • "networkDeviceSummary": true,
  • "networkDeviceDetails": [
    ],
  • "treeDetails": [
    ]
}

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

The request body contains an unrecognized network device id.

{
  • "statusName": "api:error.deviceNotFound",
  • "message": "Could not find network device by ID.",
  • "details": {
    }
}

Delete status indicators subscription (PRIVATE)

Deletes a subscription to status indicators.

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Responses

Request samples

curl --request DELETE \
  --url https://metasys-server.example.com/api/v5/statusIndicators/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

streaming

Your Metasys system works continuously: sensors report current conditions, algorithms make adjustments, and alarms alert operators to potential issues. Streaming is how the Metasys API provides access to these events using the HTML standard server-sent events (SSE). For further information, refer to Mozilla developer guide. In this document, Streaming typically refers to the Metasys feature and stream refers to the concept of the HTTP connection and the flow of data.

Per the standard, a server-sent event usually contains three components, separated by newline, with the last component having a second newline to mark the end of the event.

id: <event id>\n
event: <event type>\n
data: <event data>\n\n
Line Prefix Explanation
id ordering id to enable the "pick up where you left off" reconnection
event message type
data message payload as a JSON string

Example:

id: b6d184ee-e137-44aa-b9b1-14bc704cd25d:1\n
event: hello\n
data: b6d184ee-e137-44aa-b9b1-14bc704cd25d\n\n

Getting Started

To get started, you first need a client. There are SSE clients available in many languages.

Begin by getting a stream. Only one stream is needed regardless of the number of subscriptions you later create. As explained in the documentation for getting a stream, the first event, hello, is a special event because the data field contains your stream ID.

Some operations support the METASYS-SUBSCRIBE header which transforms them from being a single request/response operations into a streaming subscription. The value of the header is the stream ID from the data field of the hello event described above. As an example, refer to the Get Activities operation for more details about this technique. This technique does not apply to every operation. See each operation's description to understand its Streaming capability.

Not all event data is currently exposed by Streaming. Future versions of the API will add further Streaming capabilities.

Streaming Connection Maintenance

There are a few behaviors to be aware of if you want your stream to work beyond the lifetime of the access token used to get your stream.

Keep Events Flowing After Initial Access Token Expiration

Recall that your access token has an expiration time. To keep the stream longer than the lifetime of that access token, be sure to refresh your token just as you would when using non-Streaming portions of the API. Not only will you get a fresh token to use, but internally, your stream expirations are updated to match the expiration time of the new token.

Reconnect and Using the Current Access Token in Reconnect Requests

The server-sent events standard has a provision for reconnecting a lost connection. Call the same get a stream operation but also add the Last-Event-Id header with the id of the last event received. Most clients handle this for you. Metasys continues to buffer events for at least thirty seconds after the connection failure is detected, so you can resume streams that experienced brief outages. If Metasys has cleaned up your buffer or cannot find that id in the recently sent buffer, you will get a 204 response per the SSE specification. Because your existing stream is not resumable, your Last-Event-Id is no longer valid. The recovery path is to start anew by calling get a stream without the Last-Event-Id and subscribe again to data of interest.

One critical aspect of reconnect is ensuring that the reconnect request is done with the current access token. As covered by get a stream, Streaming lets you specify the token in either the Authorization header or query string. This flexibility accommodates a variety of clients. For example, the web browser client, EventSource, does not provide access to request headers, so you have to use the query string.

For EventSource, this however poses an issue because the reconnect attempt will be done against the original URL which has a potentially outdated access token embedded in the query string. For that reason, if you want to use a JavaScript client, consider using the open source EventSource component. The Metasys User Interface (MUI) employs this library to workaround the limitation of the browser's EventSource . When using it, use the Authorization header instead. Keep the options object passed to the constructor so you can update the Authorization property when you refresh your access token.

Assuming:

  1. Your access token is in variable accessToken
  2. Variable streamingUrl is the URL for get a stream
const eventSourceOptions = {
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
};

const eventSource = new $window.EventSourcePolyfill(
  streamingUrl,
  eventSourceOptions
);

Before token expiration:

  1. Get a refreshed token. Behind the scenes this also refreshes you stream expirations.
  2. Modify eventSourceOptions with new token like example below
eventSourceOptions.headers.Authorization = `Bearer ${newToken}`;

Tips For Other Client Libraries

SSE clients exist in many languages. Inclusion in this section is not an endorsement; however, if you chose one of these clients, these tips may prove useful for ensuring the current token is used for reconnect.

C# - 3ventic EventSource

When using the 3ventic EventSource for C# you will need to use Reflection to update Uri which is a private field within the EventSource that contains the location to get a stream with the access token embedded in the query string.

public static void SetField(Object obj, String fieldName, object value)
{
    Type type = obj.GetType();
    FieldInfo field = type.GetField(
        fieldName,
        BindingFlags.NonPublic | BindingFlags.Instance
    );
    field.SetValue(obj, value);
}

// example usage
Reflector.SetField(eventSource, "Uri", uriWithCurrentToken);

C# - LaunchDarkly EventSource

When using the LaunchDarkly EventSource for C# you will not call the Reset method to attempt a reconnect. Instead, dispose of the EventSource and then create a new instance, passing the the LastEventId from the last message and the URL to get a stream with a current access token embedded as a query string parameter.

Streaming Events

The following are types of events sent by Streaming along with example data payloads for each:

  • hello - Indicates Streaming connection was successful.

    Example Data Payload
    "b6d184ee-e137-44aa-b9b1-14bc704cd25d"
    
  • heartbeat - Indicates Streaming connection is alive.

    Example Data Payload
    "2021-02-16T16:21:10.23Z"
    

Get a stream

Opens or reconnects a Server Sent Event stream which is a prerequisite for subscribing to any dynamic updates

Authorizations:
Bearer-AuthenticationAPI-Key-Authentication
header Parameters
Last-Event-Id
string
Example: b6d184ee-e137-44aa-b9b1-14bc704cd25d:5

Providing the ID of the last event received enables a briefly broken stream to be resumed

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/stream \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Last-Event-Id: b6d184ee-e137-44aa-b9b1-14bc704cd25d:5'

Stream keep alive (PRIVATE)

Keep all streams associated to the user session alive and open without interruption until the new token expiration or closed by the client.

This is called internally by the various token refresh endpoints to simplify things for users. There is no need for a user to call this.

Authorizations:
Bearer-Authentication

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/stream/keepalive \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

system

Operations to retrieve capabilities and settings as well as modify settings.

Get system info (INTERNAL)

Retrieves some basic version and platform information of a site.

Authorizations:
Bearer-Authentication

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/system \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Get system capabilities (PRIVATE)

Returns a collection of key/value pairs that describe the capabilities of a site.

Authorizations:
Bearer-Authentication

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/system/capabilities \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "items": {
    }
}

Get system settings (PRIVATE)

Returns a set of key/value pairs that describe various system wide settings.

Authorizations:
Bearer-Authentication
query Parameters
includeSchema
boolean
Default: false
Example: includeSchema=true

Indicates whether the schema for the settings should be returned in the response.

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/system/settings?includeSchema=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "item": {
    }
}

Update system settings (PRIVATE)

Updates one or more system settings.

Authorizations:
Bearer-Authentication
Request Body schema: application/json
required
item
required
any

One or more system settings with appropriate values.

Responses

Request samples

Content type
application/json

This request body example will set two values of system settings.it sets graphics.behaviors.flash.flashType to alarmColor & graphics.behaviors.flash.flashRateInMilliseconds to 251

{
  • "item": [
    ]
}

Edit system setting (PRIVATE)

Update an individual system setting.

Authorizations:
Bearer-Authentication
path Parameters
settingId
required
string
Examples:
  • graphics.behaviors.flash.simpleSymbolFlash - Simple Symbol Flash
  • graphics.behaviors.flash.flashType - Flash Type

One of the keys in the response payload returned by Get system settings.

Request Body schema: application/json
required
item
required
any

A value appropriate for the specific setting.

Responses

Request samples

Content type
application/json
Example

This request body example will set the value of a setting to "alarmColor". This would be appropriate for a setting like graphics.behaviors.flash.flashType.

{
  • "item": "alarmColor"
}

🛠 Sync Engines (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Sync Engines

Note at 13.0, this command wasn't actually updated to be available at v5. To invoke it you need to use v4.

Authorizations:
Bearer-Authentication
Request Body schema: application/json
required
ids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

time series

This section describes the operations you can perform on time series sample data.

Origin of Time Series data

The Metasys system has two locations from which time series samples can be retrieved. The first is from the trend or log object, itself. Each object on the Metasys site whose responsibility is to generate samples will have its own buffer to store them. When samples are retrieved from the objects endpoints, they will be retrieved from their respective buffers. Time series operations that work with a buffer will include "(buffer)" in their summary.

The second location is from the repository. As samples are collected in the trend or log objects themselves, those objects (if configured and enabled) have the ability to forward that information to a repository. The repository is the location on the LAN (Local Area Network) that can receive and store historical data from one to many Metasys sources. Samples retrieved from the timeSeries endpoint are retrieved from the particular Metasys device's repository. Time series operations that work with the repository will include "(repository)" in their summary.

Subscription Streaming Events

Clients may subscribe to Objects and Network Devices streaming events. A subscription is established by providing a METASYS-SUBSCRIBE header on a GET operation of the samples resource under either the objects resource paths.

Events

The following events (with accompanying examples) are available for samples:

  • timeSeries.subscription.established - Indicates when a subscription has been established for objects samples.
subscriptionIds
required
Array of strings

List of all active subscriptionIds for this stream

message
required
string

The display string message that indicates that the subscription has been established successfully.

required
Array of objects

The collection of available items.

total
required
integer

The total number of items in the collection

{
  • "subscriptionIds": [
    ],
  • "message": "Sample subscription successful",
  • "items": [
    ],
  • "total": 1
}
  • timeSeries.subscription.cancelled - Indicates when a subscription has been cancelled for objects samples.
subscriptionIds
required
Array of strings

List of all subscriptionIds for this stream which have been cancelled.

message
required
string

The display string message that correlates to the subscriptions that have been cancelled.

{
  • "subscriptionIds": [
    ],
  • "message": "Sample subscription cancelled"
}
  • timeSeries.error - Indicates an error occurred with regards to an active samples subscription.
subscriptionIds
required
Array of strings

List of all subscription Ids for this stream for whom errors have been generated.

message
required
string

The display string message that provides information about the errors that have been generated.

required
Array of objects

The collection of available error items.

total
required
integer

The total number of items in the collection

{
  • "subscriptionIds": [
    ],
  • "message": "There was an issue in retrieving samples",
  • "items": [
    ],
  • "total": 1
}
  • timeSeries.samples.update - Indicates new samples have been generated. Sample updates from multiple objects and attributes can be contained in a single event (each designated by their sampledByObjectId, sampledObjectId and attribute properties).
subscriptionIds
required
Array of strings

List of all subscription IDs that the updates apply to for this stream

total
required
integer

The total number of items in the collection

required
Array of objects

A collection of sample update information for the subscribed data with additional identifying information for the objects and attributes the updates apply to.

{
  • "subscriptionIds": [
    ],
  • "total": 2,
  • "items": [
    ]
}
  • timeSeries.heartbeat - Indicates that time series subscription(s) are still alive.
currentTime
required
string <date-time>

Current server time in ISO8601 format

subscriptionIds
required
Array of strings

List of all active subscriptionIds for this stream

{
  • "currentTime": "2022-01-01T00:00:00Z",
  • "subscriptionIds": [
    ]
}

Metasys-Call-Async Streaming Events

Clients may subscribe to Objects Samples Response streaming events. A subscription is established by providing a METASYS-CALL-ASYNC header on a GET operation of the samples resource under either the objects resource paths or POST operation of the samples resource under batch operation of times buffer. The following events (with accompanying examples) are available for samples:

Events

The following events (with accompanying examples) are available for async samples:

  • timeSeries.samples.stream.started - Indicates when a subscription has been established for objects samples response.
subscriptionIds
required
Array of strings

List of all active subscriptionIds for this stream

message
required
string

The display string message that indicates that the subscription has been established successfully.

required
Array of objects

The collection of available items.

total
required
integer

The total number of items in the collection

{
  • "subscriptionIds": [
    ],
  • "message": "Sample subscription successful",
  • "items": [
    ],
  • "total": 1
}
  • timeSeries.samples.stream.error - Indicates an error occurred with regards to an active samples response subscription.
subscriptionIds
required
Array of strings

List of all subscriptionIds for this async stream which an error has been generated,

message
required
string

The display string message that correlates to an error has occurred in async stream.

{
  • "subscriptionIds": [
    ],
  • "message": "An error occurred while streaming samples."
}
  • timeSeries.samples.stream.data - Indicates samples responses for each request. Samples from multiple objects and attributes can be contained in a single event (each designated by their sampledByObjectId, sampledObjectId and attribute properties).
subscriptionIds
required
Array of strings

List of all subscription IDs that the updates apply to for this stream

total
required
integer

The total number of items in the collection

required
Array of objects

A collection of sample update information for the subscribed data with additional identifying information for the objects and attributes the updates apply to.

{
  • "subscriptionIds": [
    ],
  • "total": 2,
  • "items": [
    ]
}
  • timeSeries.samples.stream.completed - Indicates that a streaming samples response has completed successfully.
subscriptionIds
required
Array of strings

List of all subscriptionIds for this async stream which has been completed.

message
required
string

The display string message that correlates to the completion of an async samples response.

{
  • "subscriptionIds": [
    ],
  • "message": "Samples stream response completed"
}

List all time series (repository)

The operation retrieves a collection of resources for which historical time series data exists. This operation uses the time series repository as its source of truth. It may contain data for objects that no longer actually exist on the site. This operation never considers time series that exist exclusively in buffers on devices and that are not configured to forward their samples to the repository.

Authorizations:
Bearer-Authentication
query Parameters
searchString
string
Examples:
  • searchString=AV - Find all references with `AV`` in them
  • searchString=Programming - Find all references with `Programming`` in them

Filter results by finding objects with an itemReference that contains the searchString as a substring.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 2000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "itemReference"
Enum: "itemReference" "-itemReference"
Example: sort=itemReference

The criteria to use when sorting results (see rules).

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/timeSeries?searchString=AV&page=1&pageSize=100&sort=itemReference' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

List trended attributes (buffer)

Retrieves a collection of attributes under the specified object for which samples are available in their respective local sample buffers.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get objects trended attributes response.

{}

List trended attributes (repository)

Retrieves a collection of attributes for the specified object for which samples are available in the trend repository.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/timeSeries/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get trended attributes from the trend repository response.

Get attribute samples (buffer)

Retrieves a collection of samples from the object's local sample buffer for the specified object attribute during a particular date and time range.

If the METASYS-SUBSCRIBE header is provided, then an event subscription will be created which will include the events described in Time Series.

Note: The parent endpoint /objects/{objectId}/trendedAttributes/{attributeId} is not currently supported.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

attributeId
required
string
Example: presentValue
metasysType: enum
metasysEnum: attributeEnumSet

The identifier of the attribute.

The acceptable values for this parameter come from the attributeEnumSet enumeration. It is acceptable to use the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) because the enumeration set is known from context. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

query Parameters
startSampleTime
string <date-time>
Example: startSampleTime=2020-05-12T16:46:47Z

The date and time representing the earliest sample to return.

endSampleTime
string <date-time>
Example: endSampleTime=2021-01-19T18:13:58.007Z

The date and time representing the latest sample to return.

sort
string
Default: "-sampleTime"
Enum: "sampleTime" "-sampleTime"
Example: sort=sampleTime

The criteria to use when sorting results (see rules).

sampledById
Array of strings
Examples:
  • sampledById=4cc1cb52-b2db-4129-ac93-0d4a5e6dd6d7&sampledById=4ffd6456-3d36-5e08-8efb-ba91d4a81126 - Multiple identifiers
  • sampledById=4ffd6456-3d36-5e08-8efb-ba91d4a81126 - Single identifier

Filter samples by objects by supplying one or more sampledById values.

An attribute may have multiple objects sampling it. Use this parameter to include samples only from a specific object or set of objects. If no value is given for this parameter, then the response will contain samples from all of the objects sampling this attribute.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes/presentValue/samples?startSampleTime=2020-05-12T16%3A46%3A47Z&endSampleTime=2021-01-19T18%3A13%3A58.007Z&sort=sampleTime&sampledById=4cc1cb52-b2db-4129-ac93-0d4a5e6dd6d7&sampledById=4ffd6456-3d36-5e08-8efb-ba91d4a81126' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

Get samples from trend object response containing only analog values.

{}

Get attribute samples (repository)

Retrieves a collection of samples from the trend repository for the specified object attribute during a particular date and time range. Note: The parent endpoint /timeSeries/{objectId}/trendedAttributes/{attributeId} is not currently supported.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

attributeId
required
string
Example: presentValue
metasysType: enum
metasysEnum: attributeEnumSet

The identifier of the attribute.

The acceptable values for this parameter come from the attributeEnumSet enumeration. It is acceptable to use the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) because the enumeration set is known from context. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

query Parameters
startSampleTime
string <date-time>
Example: startSampleTime=2020-05-12T16:46:47Z

The date and time representing the earliest sample to return.

endSampleTime
string <date-time>
Example: endSampleTime=2021-01-19T18:13:58.007Z

The date and time representing the latest sample to return.

page
integer >= 1
Default: 1
Example: page=5

The page of the collection being requested.

pageSize
integer <= 20000
Default: 500
Example: pageSize=500

The requested number of items in the response.

sort
string
Default: "-sampleTime"
Enum: "sampleTime" "-sampleTime"
Example: sort=sampleTime

The criteria to use when sorting results. Please refer to default sorting rules for general guidelines.

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/timeSeries/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes/presentValue/samples?startSampleTime=2020-05-12T16%3A46%3A47Z&endSampleTime=2021-01-19T18%3A13%3A58.007Z&page=5&pageSize=500&sort=sampleTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

Get samples from the trend repository response containing only analog values.

{}

Get samples from trend object (buffer) (PRIVATE)

Retrieves a collection of samples from the trend object's local sample buffer for a specific time range. This operation only applies to trend objects which are objects that have an objectType of trendLogClass, trendMapperClass, bacnetTrendLogExtClass, trendLogNoextensionClass, bacnetTrendLogClass or bacnetTrendLogMultipleClass.

If the METASYS-SUBSCRIBE header is provided, then an event subscription will be created which will include the events described in Time Series.

If the METASYS-CALL-ASYNC header is provided, then an event subscription will be created and the API response will be streamed through events described in Time Series.

Note: This differs from Get attribute samples (buffer) which fetches the samples for a specific attribute of an object. Get attribute samples can be called on any object that has one or more trended attributes. However this call is only applicable to trend objects as defined above.

visibility: private
Authorizations:
Bearer-Authentication
path Parameters
trendObjectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of a trend object.

The specified object must have an objectType of trendLogClass, trendMapperClass, bacnetTrendLogExtClass, trendLogNoextensionClass, bacnetTrendLogClass or bacnetTrendLogMultipleClass.

query Parameters
startSampleTime
string <date-time>
Example: startSampleTime=2020-05-12T16:46:47Z

The date and time representing the earliest sample to return.

endSampleTime
string <date-time>
Example: endSampleTime=2021-01-19T18:13:58.007Z

The date and time representing the latest sample to return.

sort
string
Default: "-sampleTime"
Enum: "sampleTime" "-sampleTime"
Example: sort=sampleTime

The criteria to use when sorting results.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

METASYS-CALL-ASYNC
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b
visibility: private

(PRIVATE) If present, instructs the server that the operation should be invoked asynchronously. The value of this header is a stream id obtained by opening a stream with Get a stream. The operation will then return an http response immediately while the operation runs in the background. The result(s) of this operation will then be sent in one or more events over the specified stream instead of in the body of the http response.

See also:

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/samples?startSampleTime=2020-05-12T16%3A46%3A47Z&endSampleTime=2021-01-19T18%3A13%3A58.007Z&sort=sampleTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-CALL-ASYNC: 40e47e37-0f24-4101-8e1d-de96af4b648b' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json

This example shows a response to a request to get samples from a BACnet Trend Log Multiple object. The object has two Input References. One of the references is to an analog value and the other is to an enum value.

{}

List network device trended attributes (buffer) (PRIVATE)

Retrieves a collection of attributes under the specified network device for which samples are available in their respective local sample buffer.

comment: This is meant to have been deleted. See https://github.com/jci-products/cp-metasys-rest-api/pull/742 but MUI is using it. See https://github.jci.com/metasys/mui/blob/9c6eca36efc124d7ed6ac17f57ebc12a2fe3dde0/MetasysFacilityService/MetasysFacility.API/Helpers/MetasysApiModelsService.cs#L326 So we'll keep it documented and mark it private.
visibility: private
Authorizations:
Bearer-Authentication
path Parameters
id
required
string
Example: 6b092d2e-c795-4e90-95e8-5acafc74f19d

The identifier of the network device.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/networkDevices/6b092d2e-c795-4e90-95e8-5acafc74f19d/trendedAttributes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get network devices trended attributes response.

{}

Get network device samples (buffer) (PRIVATE)

Retrieves a collection of samples from the network device's local sample buffer for the specified network device attribute during a particular date and time range.

If the METASYS-SUBSCRIBE header is provided, then an event subscription will be created which will include the events described in Time Series.

Note: The parent endpoint /networkDevices/{id}/trendedAttributes/{attributeId} is not currently supported.

comment: This is meant to have been deleted. See https://github.com/jci-products/cp-metasys-rest-api/pull/742 but MUI is using it. See https://github.jci.com/metasys/mui/blob/9c6eca36efc124d7ed6ac17f57ebc12a2fe3dde0/MetasysFacilityService/MetasysFacility.API/Helpers/MetasysApiModelsService.cs#L326 So we'll keep it documented and mark it private.
visibility: private
Authorizations:
Bearer-Authentication
path Parameters
id
required
string
Example: c550095d-ee4c-4314-b415-b0577e383ee9

The identifier of the network device.

attributeId
required
string
Example: presentValue
metasysType: enum
metasysEnum: attributeEnumSet

The identifier of the attribute.

The acceptable values for this parameter come from the attributeEnumSet enumeration. It is acceptable to use the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) because the enumeration set is known from context. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

query Parameters
startSampleTime
string <date-time>
Example: startSampleTime=2020-05-12T16:46:47Z

The date and time representing the earliest sample to return.

endSampleTime
string <date-time>
Example: endSampleTime=2021-01-19T18:13:58.007Z

The date and time representing the latest sample to return.

sort
string
Default: "-sampleTime"
Enum: "sampleTime" "-sampleTime"
Example: sort=sampleTime

The criteria to use when sorting results.

sampledById
Array of strings
Examples:
  • sampledById=4cc1cb52-b2db-4129-ac93-0d4a5e6dd6d7&sampledById=4ffd6456-3d36-5e08-8efb-ba91d4a81126 - Multiple identifiers
  • sampledById=4ffd6456-3d36-5e08-8efb-ba91d4a81126 - Single identifier

Filter samples by objects by supplying one or more sampledById values.

An attribute may have multiple objects sampling it. Use this parameter to include samples only from a specific object or set of objects. If no value is given for this parameter, then the response will contain samples from all of the objects sampling this attribute.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/networkDevices/c550095d-ee4c-4314-b415-b0577e383ee9/trendedAttributes/presentValue/samples?startSampleTime=2020-05-12T16%3A46%3A47Z&endSampleTime=2021-01-19T18%3A13%3A58.007Z&sort=sampleTime&sampledById=4cc1cb52-b2db-4129-ac93-0d4a5e6dd6d7&sampledById=4ffd6456-3d36-5e08-8efb-ba91d4a81126' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

Get samples from trend object response containing only analog values.

{}

Batch operations for time series (buffer) (PRIVATE)

This operation is used to invoke multiple time series operations in a single HTTP request. Often a batch request is more efficient than sending each individual operation in its own HTTP request. In this version of the API, the only time series related operations that can be used in this batch API are List object trended attributes (buffer), Get attribute samples (buffer) and Get object samples (buffer). This request is for fetching buffer data (as opposed to fetching data from the repository).

If the METASYS-CALL-ASYNC header is provided, then an event subscription will be created and the API response will be streamed through events described in Time Series.

visibility: private
Authorizations:
Bearer-Authentication
header Parameters
METASYS-CALL-ASYNC
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b
visibility: private

(PRIVATE) If present, instructs the server that the operation should be invoked asynchronously. The value of this header is a stream id obtained by opening a stream with Get a stream. The operation will then return an http response immediately while the operation runs in the background. The result(s) of this operation will then be sent in one or more events over the specified stream instead of in the body of the http response.

See also:

Request Body schema: application/json
required
method
required
string
Value: "GET"

The HTTP method to use for each request. This property is restricted to GET for this version of the API.

required
Array of objects (Request object) non-empty

A collection of entries that represent the operations to invoke.

Responses

Request samples

Content type
application/json
Example

This example shows a request body that will read samples for the presentValue and enabled attributes for object 960534d2-7df5-5ed8-884c-164e7a2f280a and for the presentValue attribute of object c82d160b-884c-5eac-bad4-89754f0069e0.

{
  • "method": "GET",
  • "requests": [
    ]
}

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

The response to a batch request to fetch samples for three different attributes.

{}

Batch operations for time series (repository)

This operation is used to invoke multiple time series operations in a single HTTP request. Often a batch request is more efficient than sending each individual operation in its own HTTP request. In this version of the API, the only time series related operations that can be used in this batch API are Get object samples (repository). This request is for fetching repository data (as opposed to fetching data from the buffer).

Authorizations:
Bearer-Authentication
Request Body schema: application/json
required
method
required
string
Value: "GET"

The HTTP method to use for each request. This property is restricted to GET for this version of the API.

required
Array of objects (Request object) non-empty

A collection of entries that represent the operations to invoke.

Responses

Request samples

Content type
application/json

This example shows a request body that will read samples for the presentValue and enabled attributes for object c550095d-ee4c-4314-b415-b0577e383ee9 and for the presentValue attribute of object c82d160b-884c-5eac-bad4-89754f0069e0.

{
  • "method": "GET",
  • "requests": [
    ]
}

Response samples

Content type
application/vnd.metasysapi.v5+json

The response to a batch request to fetch samples for three different attributes.

{}

Create samples subscription (buffer)

Creates a subscription to trend buffer samples

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

Request Body schema: application/json
required

New streaming subscription for time series data.

Array of objects

Collection of items to sign up for.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Update samples subscription (buffer)

Replaces an existing subscription to trend buffer samples.

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Request Body schema: application/json
required

Streaming subscription for time series data.

Array of objects

Collection of items to sign up for.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Delete trend samples subscription

Deletes a subscription to trend samples.

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Responses

Request samples

curl --request DELETE \
  --url https://metasys-server.example.com/api/v5/timeSeries/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

user queries

Operations to retrieve information about users.

Get status of all users (INTERNAL)

Retrieves a list of users for the well-known user status query. Status information in the query includes account status and dormancy details to provide an overview of user activity on the system.

Note: At this release, this operation is only supported when the networkDeviceId is for the site director device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the network device object for a well known query.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/networkDevices/5a22812f-ec51-4c11-ab4a-fc986f94f008/wellKnownQueries/userStatus \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get all users on the device with their status, including dormancy of each account based on activity.

{
  • "items": [
    ]
}

users

Operations to retrieve and modify user accounts.

🛠 List users (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Retrieves a collection of users.

Authorizations:
Bearer-Authentication
query Parameters
roles
Array of strings
Example: roles=USER&roles=OPERATOR

Filter by role. The list of roles can be found by calling GET /roles.

See also:

userLastLoggedinAfter
string <date-time>
Example: userLastLoggedinAfter=2022-08-05T05:00:00Z

Only include users that have logged in after this date-time.

userLastLoggedinBefore
string <date-time>
Example: userLastLoggedinBefore=2022-08-05T05:00:00Z

Only include users that have logged in before this date-time.

excludeMetasysUsers
boolean
Default: false
Example: excludeMetasysUsers=true

Indicates if metasys (local) user accounts should be excluded from the results.

Note: You will get a 400 (BadRequest) status code if you set this to true and active directory authentication is not enabled.

excludeRadiusUsers
boolean
Default: false
Example: excludeRadiusUsers=true

Indicates if RADIUS user accounts should be excluded from the results.

excludeADUsers
boolean
Default: false
Example: excludeADUsers=true

Indicates if active directory user accounts should be excluded from the results.

q
string
Example: q=true

A search string used to filter results. At a minimum userName and description properties of a user account are searched.

page
integer
Default: 1
Example: page=3

Results are returned in paged collections. This parameter specifies which page to return.

pageSize
integer
Default: 100
Example: pageSize=50

Results are returned in paged collections. This parameter specifies how many results to include per page.

sort
string
Default: "userName"
Enum: "fullName" "-fullName" "lastLogin" "-lastLogin" "primaryEmail" "-primaryEmail" "userName" "-userName"
Example: sort=userName

The criteria to use when sorting results (see rules).

format
string
Enum: "pdf" "csv"
Example: format=csv

The normal response is JSON. Use the format parameter to request a pdf or csv response.

Responses

Request samples

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/users?roles=USER&roles=OPERATOR&userLastLoggedinAfter=2022-08-05T05%3A00%3A00Z&userLastLoggedinBefore=2022-08-05T05%3A00%3A00Z&excludeMetasysUsers=true&excludeRadiusUsers=true&excludeADUsers=true&q=true&page=3&pageSize=50&sort=userName&format=csv' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

🛠 Get user (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Retrieves a specific user account.

This operation requires admin privileges.

Authorizations:
Bearer-Authentication
path Parameters
userId
required
string
Example: anNtaXRo

The identifier of the user to retrieve.

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/users/anNtaXRo \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example
{
  • "userName": "jsmith",
  • "profile": {},
  • "permissions": {
    },
  • "roles": null,
  • "userViews": {
    }
}

🛠 Edit user (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Edit a user

comments: This operation is very problematic. The request body is an exact duplicate of the response body of GET /users/{userId}. And that body has some properties duplicated (even more than once). So it's not at all obvious what happens if you change one of those properties; but in only one location. It's also not clear what properties are required, what their defaults might be. This will need to be fixed before every making public or internal.
Authorizations:
Bearer-Authentication
path Parameters
userId
required
string
Example: anNtaXRo

The identifier of the user to retrieve.

Request Body schema: application/json
required
userName
string
object
object
object or null
object

Responses

Request samples

Content type
application/json
{
  • "userName": "api-user",
  • "profile": {},
  • "permissions": {
    },
  • "roles": null,
  • "userViews": {
    }
}

🛠 Get current user (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Get information about the user account of the current session.

Authorizations:
Bearer-Authentication

Responses

Request samples

curl --request GET \
  --url https://metasys-server.example.com/api/v5/userinfo \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "userName": "api-user",
  • "profile": {},
  • "permissions": {
    },
  • "roles": null,
  • "userViews": {
    }
}

z-dummy-ops

The set of dummy operations used only to get validation of our server-sent events. These should all be hidden visibility.

🛠 Sample heartbeat (HIDDEN)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

undefined

Authorizations:
Bearer-Authentication
Request Body schema: application/json
subscriptionIds
required
Array of strings

List of all active subscriptionIds for this stream

Responses

Request samples

Content type
application/json
{
  • "currentTime": "2022-01-01T00:00:00Z",
  • "subscriptionIds": [
    ]
}

🛠 Sample Established (HIDDEN)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

undefined

Authorizations:
Bearer-Authentication
Request Body schema: application/json
subscriptionIds
required
Array of strings

List of all active subscriptionIds for this stream

required
Array of objects

The collection of available items.

total
required
integer

The total number of items in the collection

Responses

Request samples

Content type
application/json
{
  • "subscriptionIds": [
    ],
  • "message": "Sample subscription successful",
  • "items": [
    ],
  • "total": 1
}

🛠 Sample Error (HIDDEN)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

undefined

Authorizations:
Bearer-Authentication
Request Body schema: application/json
subscriptionIds
required
Array of strings

List of all subscription Ids for this stream for whom errors have been generated.

required
Array of objects

The collection of available error items.

total
required
integer

The total number of items in the collection

Responses

Request samples

Content type
application/json
{
  • "subscriptionIds": [
    ],
  • "message": "There was an issue in retrieving samples",
  • "items": [
    ],
  • "total": 1
}

🛠 Sample Cancelled (HIDDEN)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

undefined

Authorizations:
Bearer-Authentication
Request Body schema: application/json
subscriptionIds
required
Array of strings

List of all subscriptionIds for this stream which have been cancelled.

message
required
string

The display string message that correlates to the subscriptions that have been cancelled.

Responses

Request samples

Content type
application/json
{
  • "subscriptionIds": [
    ],
  • "message": "Sample subscription cancelled"
}

🛠 Sample Update (HIDDEN)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

undefined

Authorizations:
Bearer-Authentication
Request Body schema: application/json
subscriptionIds
required
Array of strings

List of all subscription IDs that the updates apply to for this stream

total
required
integer

The total number of items in the collection

required
Array of objects

A collection of sample update information for the subscribed data with additional identifying information for the objects and attributes the updates apply to.

Responses

Request samples

Content type
application/json
{
  • "subscriptionIds": [
    ],
  • "total": 2,
  • "items": [
    ]
}

🛠 Sample Async Error (HIDDEN)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

undefined

Authorizations:
Bearer-Authentication
Request Body schema: application/json
subscriptionIds
required
Array of strings

List of all subscriptionIds for this async stream which an error has been generated,

message
required
string

The display string message that correlates to an error has occurred in async stream.

Responses

Request samples

Content type
application/json
{
  • "subscriptionIds": [
    ],
  • "message": "An error occurred while streaming samples."
}

🛠 Sample Completed (HIDDEN)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

undefined

Authorizations:
Bearer-Authentication
Request Body schema: application/json
subscriptionIds
required
Array of strings

List of all subscriptionIds for this async stream which has been completed.

message
required
string

The display string message that correlates to the completion of an async samples response.

Responses

Request samples

Content type
application/json
{
  • "subscriptionIds": [
    ],
  • "message": "Samples stream response completed"
}

🛠 undefined (HIDDEN)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

undefined

Authorizations:
Bearer-Authentication
Request Body schema: application/json
subscriptionIds
required
Array of strings

List of all active subscriptionIds for this stream

Responses

Request samples

Content type
application/json
{
  • "currentTime": "2022-01-01T00:00:00Z",
  • "subscriptionIds": [
    ]
}

🛠 undefined (HIDDEN)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

undefined

Authorizations:
Bearer-Authentication
Request Body schema: application/json
subscriptionIds
required
Array of strings <uuid> [ items <uuid > ]

Subscription IDs that the notification apply to

total
required
integer <int32>

Total alarms pending acknowledgement

object or null

Current priority alarm. If null and total is 0, then all alarms are acknowledged. If null and total is >0, then all alarms are snoozed

Responses

Request samples

Content type
application/json
Example
{
  • "subscriptionIds": [
    ],
  • "total": 5,
  • "item": {
    }
}